main branch resync

IPython/external/argparse.py

@@ -0,0 +1,1867
+# -*- coding: utf-8 -*-
+
+# Copyright � 2006 Steven J. Bethard <[e-mail]>.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted under the terms of the 3-clause BSD
+# license. No warranty expressed or implied.
+# For details, see the accompanying file LICENSE.txt.
+
+"""Command-line parsing library
+
+This module is an optparse-inspired command-line parsing library that:
+
+* handles both optional and positional arguments
+* produces highly informative usage messages
+* supports parsers that dispatch to sub-parsers
+
+The following is a simple usage example that sums integers from the
+command-line and writes the result to a file:
+
+    parser = argparse.ArgumentParser(
+        description='sum the integers at the command line')
+    parser.add_argument(
+        'integers', metavar='int', nargs='+', type=int,
+        help='an integer to be summed')
+    parser.add_argument(
+        '--log', default=sys.stdout, type=argparse.FileType('w'),
+        help='the file where the sum should be written')
+    args = parser.parse_args()
+    args.log.write('%s' % sum(args.integers))
+    args.log.close()
+
+The module contains the following public classes:
+
+    ArgumentParser -- The main entry point for command-line parsing. As the
+        example above shows, the add_argument() method is used to populate
+        the parser with actions for optional and positional arguments. Then
+        the parse_args() method is invoked to convert the args at the
+        command-line into an object with attributes.
+
+    ArgumentError -- The exception raised by ArgumentParser objects when
+        there are errors with the parser's actions. Errors raised while
+        parsing the command-line are caught by ArgumentParser and emitted
+        as command-line messages.
+
+    FileType -- A factory for defining types of files to be created. As the
+        example above shows, instances of FileType are typically passed as
+        the type= argument of add_argument() calls.
+
+    Action -- The base class for parser actions. Typically actions are
+        selected by passing strings like 'store_true' or 'append_const' to
+        the action= argument of add_argument(). However, for greater
+        customization of ArgumentParser actions, subclasses of Action may
+        be defined and passed as the action= argument.
+
+    HelpFormatter, RawDescriptionHelpFormatter -- Formatter classes which
+        may be passed as the formatter_class= argument to the
+        ArgumentParser constructor. HelpFormatter is the default, while
+        RawDescriptionHelpFormatter tells the parser not to perform any
+        line-wrapping on description text.
+
+All other classes in this module are considered implementation details.
+(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
+considered public as object names -- the API of the formatter objects is
+still considered an implementation detail.)
+"""
+
+__version__ = '0.8.0'
+
+import os as _os
+import re as _re
+import sys as _sys
+import textwrap as _textwrap
+
+from gettext import gettext as _
+
+SUPPRESS = '==SUPPRESS=='
+
+OPTIONAL = '?'
+ZERO_OR_MORE = '*'
+ONE_OR_MORE = '+'
+PARSER = '==PARSER=='
+
+# =============================
+# Utility functions and classes
+# =============================
+
+class _AttributeHolder(object):
+    """Abstract base class that provides __repr__.
+
+    The __repr__ method returns a string in the format:
+        ClassName(attr=name, attr=name, ...)
+    The attributes are determined either by a class-level attribute,
+    '_kwarg_names', or by inspecting the instance __dict__.
+    """
+    
+    def __repr__(self):
+        type_name = type(self).__name__
+        arg_strings = []
+        for arg in self._get_args():
+            arg_strings.append(repr(arg))
+        for name, value in self._get_kwargs():
+            arg_strings.append('%s=%r' % (name, value))
+        return '%s(%s)' % (type_name, ', '.join(arg_strings))
+
+    def _get_kwargs(self):
+        return sorted(self.__dict__.items())
+
+    def _get_args(self):
+        return []
+
+def _ensure_value(namespace, name, value):
+    if getattr(namespace, name, None) is None:
+        setattr(namespace, name, value)
+    return getattr(namespace, name)
+    
+
+
+# ===============
+# Formatting Help
+# ===============
+
+class HelpFormatter(object):
+
+    def __init__(self,
+                 prog,
+                 indent_increment=2,
+                 max_help_position=24,
+                 width=None):
+
+        # default setting for width
+        if width is None:
+            try:
+                width = int(_os.environ['COLUMNS'])
+            except (KeyError, ValueError):
+                width = 80
+            width -= 2
+        
+        self._prog = prog
+        self._indent_increment = indent_increment
+        self._max_help_position = max_help_position
+        self._width = width
+
+        self._current_indent = 0
+        self._level = 0
+        self._action_max_length = 0
+
+        self._root_section = self._Section(self, None)
+        self._current_section = self._root_section
+
+        self._whitespace_matcher = _re.compile(r'\s+')
+        self._long_break_matcher = _re.compile(r'\n\n\n+')
+
+    # ===============================
+    # Section and indentation methods
+    # ===============================
+
+    def _indent(self):
+        self._current_indent += self._indent_increment
+        self._level += 1
+
+    def _dedent(self):
+        self._current_indent -= self._indent_increment
+        assert self._current_indent >= 0, 'Indent decreased below 0.'
+        self._level -= 1
+
+    class _Section(object):
+        def __init__(self, formatter, parent, heading=None):
+            self.formatter = formatter
+            self.parent = parent
+            self.heading = heading
+            self.items = []
+
+        def format_help(self):
+            # format the indented section
+            if self.parent is not None:
+                self.formatter._indent()
+            join = self.formatter._join_parts
+            for func, args in self.items:
+                func(*args)
+            item_help = join(func(*args) for func, args in self.items)
+            if self.parent is not None:
+                self.formatter._dedent()
+
+            # return nothing if the section was empty            
+            if not item_help:
+                return ''
+
+            # add the heading if the section was non-empty
+            if self.heading is not SUPPRESS and self.heading is not None:
+                current_indent = self.formatter._current_indent
+                heading = '%*s%s:\n' % (current_indent, '', self.heading)
+            else:
+                heading = ''
+
+            # join the section-initial newline, the heading and the help
+            return join(['\n', heading, item_help, '\n'])
+
+    def _add_item(self, func, args):
+        self._current_section.items.append((func, args))
+
+    # ========================
+    # Message building methods
+    # ========================
+
+    def start_section(self, heading):
+        self._indent()
+        section = self._Section(self, self._current_section, heading)
+        self._add_item(section.format_help, [])
+        self._current_section = section
+
+    def end_section(self):
+        self._current_section = self._current_section.parent
+        self._dedent()
+
+    def add_text(self, text):
+        if text is not SUPPRESS and text is not None:
+            self._add_item(self._format_text, [text])
+
+    def add_usage(self, usage, optionals, positionals, prefix=None):
+        if usage is not SUPPRESS:
+            args = usage, optionals, positionals, prefix
+            self._add_item(self._format_usage, args)
+
+    def add_argument(self, action):
+        if action.help is not SUPPRESS:
+
+            # find all invocations            
+            get_invocation = self._format_action_invocation
+            invocations = [get_invocation(action)]
+            for subaction in self._iter_indented_subactions(action):
+                invocations.append(get_invocation(subaction))
+                    
+            # update the maximum item length
+            invocation_length = max(len(s) for s in invocations)
+            action_length = invocation_length + self._current_indent
+            self._action_max_length = max(self._action_max_length,
+                                          action_length)
+
+            # add the item to the list        
+            self._add_item(self._format_action, [action])
+
+    def add_arguments(self, actions):
+        for action in actions:
+            self.add_argument(action)
+
+    # =======================
+    # Help-formatting methods
+    # =======================
+
+    def format_help(self):
+        help = self._root_section.format_help() % dict(prog=self._prog)
+        if help:
+            help = self._long_break_matcher.sub('\n\n', help)
+            help = help.strip('\n') + '\n'
+        return help
+
+    def _join_parts(self, part_strings):
+        return ''.join(part
+                       for part in part_strings
+                       if part and part is not SUPPRESS)
+
+    def _format_usage(self, usage, optionals, positionals, prefix):
+        if prefix is None:
+            prefix = _('usage: ')
+
+        # if no optionals or positionals are available, usage is just prog
+        if usage is None and not optionals and not positionals:
+            usage = '%(prog)s'
+            
+        # if optionals and positionals are available, calculate usage
+        elif usage is None:
+            usage = '%(prog)s' % dict(prog=self._prog)
+                
+            # determine width of "usage: PROG" and width of text
+            prefix_width = len(prefix) + len(usage) + 1
+            prefix_indent = self._current_indent + prefix_width
+            text_width = self._width - self._current_indent
+
+            # put them on one line if they're short enough
+            format = self._format_actions_usage
+            action_usage = format(optionals + positionals)
+            if prefix_width + len(action_usage) + 1 < text_width:
+                usage = '%s %s' % (usage, action_usage)
+            
+            # if they're long, wrap optionals and positionals individually
+            else:
+                optional_usage = format(optionals)
+                positional_usage = format(positionals)
+                indent = ' ' * prefix_indent
+
+                # usage is made of PROG, optionals and positionals
+                parts = [usage, ' ']
+                
+                # options always get added right after PROG
+                if optional_usage:
+                    parts.append(_textwrap.fill(
+                        optional_usage, text_width,
+                        initial_indent=indent,
+                        subsequent_indent=indent).lstrip())
+
+                # if there were options, put arguments on the next line
+                # otherwise, start them right after PROG
+                if positional_usage:
+                    part = _textwrap.fill(
+                        positional_usage, text_width,
+                        initial_indent=indent,
+                        subsequent_indent=indent).lstrip()
+                    if optional_usage:
+                        part = '\n' + indent + part
+                    parts.append(part)
+                usage = ''.join(parts)
+
+        # prefix with 'usage:'
+        return '%s%s\n\n' % (prefix, usage)
+
+    def _format_actions_usage(self, actions):
+        parts = []
+        for action in actions:
+            if action.help is SUPPRESS:
+                continue
+
+            # produce all arg strings        
+            if not action.option_strings:
+                parts.append(self._format_args(action, action.dest))
+
+            # produce the first way to invoke the option in brackets
+            else:
+                option_string = action.option_strings[0]
+
+                # if the Optional doesn't take a value, format is:
+                #    -s or --long
+                if action.nargs == 0:
+                    part = '%s' % option_string
+
+                # if the Optional takes a value, format is:
+                #    -s ARGS or --long ARGS
+                else:
+                    default = action.dest.upper()
+                    args_string = self._format_args(action, default)
+                    part = '%s %s' % (option_string, args_string)
+
+                # make it look optional if it's not required
+                if not action.required:
+                    part = '[%s]' % part
+                parts.append(part)
+
+        return ' '.join(parts)
+
+    def _format_text(self, text):
+        text_width = self._width - self._current_indent
+        indent = ' ' * self._current_indent
+        return self._fill_text(text, text_width, indent) + '\n\n'
+
+    def _format_action(self, action):
+        # determine the required width and the entry label
+        help_position = min(self._action_max_length + 2,
+                            self._max_help_position)
+        help_width = self._width - help_position
+        action_width = help_position - self._current_indent - 2
+        action_header = self._format_action_invocation(action)
+
+        # ho nelp; start on same line and add a final newline
+        if not action.help:
+            tup = self._current_indent, '', action_header
+            action_header = '%*s%s\n' % tup
+            
+        # short action name; start on the same line and pad two spaces
+        elif len(action_header) <= action_width:
+            tup = self._current_indent, '', action_width, action_header
+            action_header = '%*s%-*s  ' % tup
+            indent_first = 0
+
+        # long action name; start on the next line
+        else:
+            tup = self._current_indent, '', action_header
+            action_header = '%*s%s\n' % tup
+            indent_first = help_position
+
+        # collect the pieces of the action help
+        parts = [action_header]
+
+        # if there was help for the action, add lines of help text
+        if action.help:
+            help_text = self._expand_help(action)
+            help_lines = self._split_lines(help_text, help_width)
+            parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
+            for line in help_lines[1:]:
+                parts.append('%*s%s\n' % (help_position, '', line))
+
+        # or add a newline if the description doesn't end with one
+        elif not action_header.endswith('\n'):
+            parts.append('\n')
+
+        # if there are any sub-actions, add their help as well
+        for subaction in self._iter_indented_subactions(action):
+            parts.append(self._format_action(subaction))
+
+        # return a single string            
+        return self._join_parts(parts)
+
+    def _format_action_invocation(self, action):
+        if not action.option_strings:
+            return self._format_metavar(action, action.dest)
+
+        else:
+            parts = []
+
+            # if the Optional doesn't take a value, format is:
+            #    -s, --long
+            if action.nargs == 0:
+                parts.extend(action.option_strings)
+
+            # if the Optional takes a value, format is:
+            #    -s ARGS, --long ARGS
+            else:
+                default = action.dest.upper()
+                args_string = self._format_args(action, default)
+                for option_string in action.option_strings:
+                    parts.append('%s %s' % (option_string, args_string))
+
+            return ', '.join(parts)
+
+    def _format_metavar(self, action, default_metavar):
+        if action.metavar is not None:
+            name = action.metavar
+        elif action.choices is not None:
+            choice_strs = (str(choice) for choice in action.choices)
+            name = '{%s}' % ','.join(choice_strs)
+        else:
+            name = default_metavar
+        return name
+
+    def _format_args(self, action, default_metavar):
+        name = self._format_metavar(action, default_metavar)
+        if action.nargs is None:
+            result = name
+        elif action.nargs == OPTIONAL:
+            result = '[%s]' % name
+        elif action.nargs == ZERO_OR_MORE:
+            result = '[%s [%s ...]]' % (name, name)
+        elif action.nargs == ONE_OR_MORE:
+            result = '%s [%s ...]' % (name, name)
+        elif action.nargs is PARSER:
+            result = '%s ...' % name
+        else:
+            result = ' '.join([name] * action.nargs)
+        return result
+
+    def _expand_help(self, action):
+        params = dict(vars(action), prog=self._prog)
+        for name, value in params.items():
+            if value is SUPPRESS:
+                del params[name]
+        if params.get('choices') is not None:
+            choices_str = ', '.join(str(c) for c in params['choices'])
+            params['choices'] = choices_str
+        return action.help % params
+
+    def _iter_indented_subactions(self, action):
+        try:
+            get_subactions = action._get_subactions
+        except AttributeError:
+            pass
+        else:
+            self._indent()
+            for subaction in get_subactions():
+                yield subaction
+            self._dedent()
+
+    def _split_lines(self, text, width):
+        text = self._whitespace_matcher.sub(' ', text).strip()
+        return _textwrap.wrap(text, width)
+
+    def _fill_text(self, text, width, indent):
+        text = self._whitespace_matcher.sub(' ', text).strip()
+        return _textwrap.fill(text, width, initial_indent=indent,
+                                           subsequent_indent=indent)
+
+class RawDescriptionHelpFormatter(HelpFormatter):
+    
+    def _fill_text(self, text, width, indent):
+        return ''.join(indent + line for line in text.splitlines(True))
+
+class RawTextHelpFormatter(RawDescriptionHelpFormatter):
+    
+    def _split_lines(self, text, width):
+        return text.splitlines()
+
+# =====================
+# Options and Arguments
+# =====================
+
+class ArgumentError(Exception):
+    """ArgumentError(message, argument)
+
+    Raised whenever there was an error creating or using an argument
+    (optional or positional).
+
+    The string value of this exception is the message, augmented with
+    information about the argument that caused it.
+    """
+    
+    def __init__(self, argument, message):
+        if argument.option_strings:
+            self.argument_name =  '/'.join(argument.option_strings)
+        elif argument.metavar not in (None, SUPPRESS):
+            self.argument_name = argument.metavar
+        elif argument.dest not in (None, SUPPRESS):
+            self.argument_name = argument.dest
+        else:
+            self.argument_name = None
+        self.message = message
+
+    def __str__(self):
+        if self.argument_name is None:
+            format = '%(message)s'
+        else:
+            format = 'argument %(argument_name)s: %(message)s'
+        return format % dict(message=self.message,
+                             argument_name=self.argument_name)
+
+# ==============
+# Action classes
+# ==============
+
+class Action(_AttributeHolder):
+    """Action(*strings, **options)
+
+    Action objects hold the information necessary to convert a
+    set of command-line arguments (possibly including an initial option
+    string) into the desired Python object(s).
+
+    Keyword Arguments:
+
+    option_strings -- A list of command-line option strings which
+        should be associated with this action.
+    
+    dest -- The name of the attribute to hold the created object(s)
+    
+    nargs -- The number of command-line arguments that should be consumed.
+        By default, one argument will be consumed and a single value will
+        be produced.  Other values include:
+            * N (an integer) consumes N arguments (and produces a list)
+            * '?' consumes zero or one arguments
+            * '*' consumes zero or more arguments (and produces a list)
+            * '+' consumes one or more arguments (and produces a list)
+        Note that the difference between the default and nargs=1 is that
+        with the default, a single value will be produced, while with
+        nargs=1, a list containing a single value will be produced.
+
+    const -- The value to be produced if the option is specified and the
+        option uses an action that takes no values.
+
+    default -- The value to be produced if the option is not specified.
+
+    type -- The type which the command-line arguments should be converted
+        to, should be one of 'string', 'int', 'float', 'complex' or a
+        callable object that accepts a single string argument. If None,
+        'string' is assumed.
+        
+    choices -- A container of values that should be allowed. If not None,
+        after a command-line argument has been converted to the appropriate
+        type, an exception will be raised if it is not a member of this
+        collection.
+
+    required -- True if the action must always be specified at the command
+        line. This is only meaningful for optional command-line arguments.
+
+    help -- The help string describing the argument.
+
+    metavar -- The name to be used for the option's argument with the help
+        string. If None, the 'dest' value will be used as the name.
+    """
+
+
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 nargs=None,
+                 const=None,
+                 default=None,
+                 type=None,
+                 choices=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
+        self.option_strings = option_strings
+        self.dest = dest
+        self.nargs = nargs
+        self.const = const
+        self.default = default
+        self.type = type
+        self.choices = choices
+        self.required = required
+        self.help = help
+        self.metavar = metavar
+
+    def _get_kwargs(self):
+        names = [
+            'option_strings',
+            'dest',
+            'nargs',
+            'const',
+            'default',
+            'type',
+            'choices',
+            'help',
+            'metavar'
+        ]
+        return [(name, getattr(self, name)) for name in names]
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        raise NotImplementedError(_('.__call__() not defined'))
+
+class _StoreAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 nargs=None,
+                 const=None,
+                 default=None,
+                 type=None,
+                 choices=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
+        if nargs == 0:
+            raise ValueError('nargs must be > 0')
+        if const is not None and nargs != OPTIONAL:
+            raise ValueError('nargs must be %r to supply const' % OPTIONAL)
+        super(_StoreAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=nargs,
+            const=const,
+            default=default,
+            type=type,
+            choices=choices,
+            required=required,
+            help=help,
+            metavar=metavar)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        setattr(namespace, self.dest, values)
+
+class _StoreConstAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 const,
+                 default=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
+        super(_StoreConstAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=0,
+            const=const,
+            default=default,
+            required=required,
+            help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        setattr(namespace, self.dest, self.const)
+
+class _StoreTrueAction(_StoreConstAction):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 default=False,
+                 required=False,
+                 help=None):
+        super(_StoreTrueAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            const=True,
+            default=default,
+            required=required,
+            help=help)
+
+class _StoreFalseAction(_StoreConstAction):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 default=True,
+                 required=False,
+                 help=None):
+        super(_StoreFalseAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            const=False,
+            default=default,
+            required=required,
+            help=help)
+    
+class _AppendAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 nargs=None,
+                 const=None,
+                 default=None,
+                 type=None,
+                 choices=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
+        if nargs == 0:
+            raise ValueError('nargs must be > 0')
+        if const is not None and nargs != OPTIONAL:
+            raise ValueError('nargs must be %r to supply const' % OPTIONAL)
+        super(_AppendAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=nargs,
+            const=const,
+            default=default,
+            type=type,
+            choices=choices,
+            required=required,
+            help=help,
+            metavar=metavar)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        _ensure_value(namespace, self.dest, []).append(values)
+
+class _AppendConstAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 const,
+                 default=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
+        super(_AppendConstAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=0,
+            const=const,
+            default=default,
+            required=required,
+            help=help,
+            metavar=metavar)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        _ensure_value(namespace, self.dest, []).append(self.const)
+
+class _CountAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 default=None,
+                 required=False,
+                 help=None):
+        super(_CountAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=0,
+            default=default,
+            required=required,
+            help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        new_count = _ensure_value(namespace, self.dest, 0) + 1
+        setattr(namespace, self.dest, new_count)
+
+class _HelpAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest=SUPPRESS,
+                 default=SUPPRESS,
+                 help=None):
+        super(_HelpAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            default=default,
+            nargs=0,
+            help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser.print_help()
+        parser.exit()
+
+class _VersionAction(Action):
+    def __init__(self,
+                 option_strings,
+                 dest=SUPPRESS,
+                 default=SUPPRESS,
+                 help=None):
+        super(_VersionAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            default=default,
+            nargs=0,
+            help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser.print_version()
+        parser.exit()
+        
+class _SubParsersAction(Action):
+
+    class _ChoicesPseudoAction(Action):
+        def __init__(self, name, help):
+            sup = super(_SubParsersAction._ChoicesPseudoAction, self)
+            sup.__init__(option_strings=[], dest=name, help=help)
+
+        
+    def __init__(self,
+                 option_strings,
+                 prog,
+                 parser_class,
+                 dest=SUPPRESS,
+                 help=None,
+                 metavar=None):
+        
+        self._prog_prefix = prog
+        self._parser_class = parser_class
+        self._name_parser_map = {}
+        self._choices_actions = []
+
+        super(_SubParsersAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            nargs=PARSER,
+            choices=self._name_parser_map,
+            help=help,
+            metavar=metavar)
+
+    def add_parser(self, name, **kwargs):
+        # set prog from the existing prefix
+        if kwargs.get('prog') is None:
+            kwargs['prog'] = '%s %s' % (self._prog_prefix, name)
+
+        # create a pseudo-action to hold the choice help
+        if 'help' in kwargs:
+            help = kwargs.pop('help')
+            choice_action = self._ChoicesPseudoAction(name, help)
+            self._choices_actions.append(choice_action)
+
+        # create the parser and add it to the map
+        parser = self._parser_class(**kwargs)
+        self._name_parser_map[name] = parser
+        return parser
+
+    def _get_subactions(self):
+        return self._choices_actions
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser_name = values[0]
+        arg_strings = values[1:]
+
+        # set the parser name if requested
+        if self.dest is not SUPPRESS:
+            setattr(namespace, self.dest, parser_name)
+
+        # select the parser        
+        try:
+            parser = self._name_parser_map[parser_name]
+        except KeyError:
+            tup = parser_name, ', '.join(self._name_parser_map)
+            msg = _('unknown parser %r (choices: %s)' % tup)
+            raise ArgumentError(self, msg)
+
+        # parse all the remaining options into the namespace
+        parser.parse_args(arg_strings, namespace)
+
+
+# ==============
+# Type classes
+# ==============
+
+class FileType(object):
+    """Factory for creating file object types
+
+    Instances of FileType are typically passed as type= arguments to the
+    ArgumentParser add_argument() method.
+
+    Keyword Arguments:
+    mode -- A string indicating how the file is to be opened. Accepts the
+        same values as the builtin open() function.
+    bufsize -- The file's desired buffer size. Accepts the same values as
+        the builtin open() function.
+    """    
+    def __init__(self, mode='r', bufsize=None):
+        self._mode = mode
+        self._bufsize = bufsize
+    
+    def __call__(self, string):
+        # the special argument "-" means sys.std{in,out}
+        if string == '-':
+            if self._mode == 'r':
+                return _sys.stdin
+            elif self._mode == 'w':
+                return _sys.stdout
+            else:
+                msg = _('argument "-" with mode %r' % self._mode)
+                raise ValueError(msg)
+
+        # all other arguments are used as file names
+        if self._bufsize:
+            return open(string, self._mode, self._bufsize)
+        else:
+            return open(string, self._mode)
+
+
+# ===========================
+# Optional and Positional Parsing
+# ===========================
+
+class Namespace(_AttributeHolder):
+
+    def __init__(self, **kwargs):
+        for name, value in kwargs.iteritems():
+            setattr(self, name, value)
+
+    def __eq__(self, other):
+        return vars(self) == vars(other)
+
+    def __ne__(self, other):
+        return not (self == other)
+
+
+class _ActionsContainer(object):
+    def __init__(self,
+                 description,
+                 prefix_chars,
+                 argument_default,
+                 conflict_handler):
+        super(_ActionsContainer, self).__init__()
+
+        self.description = description
+        self.argument_default = argument_default
+        self.prefix_chars = prefix_chars
+        self.conflict_handler = conflict_handler
+
+        # set up registries
+        self._registries = {}
+
+        # register actions
+        self.register('action', None, _StoreAction)
+        self.register('action', 'store', _StoreAction)
+        self.register('action', 'store_const', _StoreConstAction)
+        self.register('action', 'store_true', _StoreTrueAction)
+        self.register('action', 'store_false', _StoreFalseAction)
+        self.register('action', 'append', _AppendAction)
+        self.register('action', 'append_const', _AppendConstAction)
+        self.register('action', 'count', _CountAction)
+        self.register('action', 'help', _HelpAction)
+        self.register('action', 'version', _VersionAction)
+        self.register('action', 'parsers', _SubParsersAction)
+        
+        # raise an exception if the conflict handler is invalid
+        self._get_handler()
+
+        # action storage
+        self._optional_actions_list = []
+        self._positional_actions_list = []
+        self._positional_actions_full_list = []
+        self._option_strings = {}
+
+        # defaults storage
+        self._defaults = {}
+
+    # ====================
+    # Registration methods
+    # ====================
+
+    def register(self, registry_name, value, object):
+        registry = self._registries.setdefault(registry_name, {})
+        registry[value] = object
+
+    def _registry_get(self, registry_name, value, default=None):
+        return self._registries[registry_name].get(value, default)
+
+    # ==================================
+    # Namespace default settings methods
+    # ==================================
+
+    def set_defaults(self, **kwargs):
+        self._defaults.update(kwargs)
+
+        # if these defaults match any existing arguments, replace
+        # the previous default on the object with the new one
+        for action_list in [self._option_strings.values(),
+                            self._positional_actions_full_list]:
+            for action in action_list:
+                if action.dest in kwargs:
+                    action.default = kwargs[action.dest]
+
+    # =======================
+    # Adding argument actions
+    # =======================
+
+    def add_argument(self, *args, **kwargs):
+        """
+        add_argument(dest, ..., name=value, ...)
+        add_argument(option_string, option_string, ..., name=value, ...)
+        """
+
+        # if no positional args are supplied or only one is supplied and
+        # it doesn't look like an option string, parse a positional
+        # argument
+        chars = self.prefix_chars
+        if not args or len(args) == 1 and args[0][0] not in chars:
+            kwargs = self._get_positional_kwargs(*args, **kwargs)
+
+        # otherwise, we're adding an optional argument
+        else:
+            kwargs = self._get_optional_kwargs(*args, **kwargs)
+
+        # if no default was supplied, use the parser-level default
+        if 'default' not in kwargs:
+            dest = kwargs['dest']
+            if dest in self._defaults:
+                kwargs['default'] = self._defaults[dest]
+            elif self.argument_default is not None:
+                kwargs['default'] = self.argument_default
+            
+        # create the action object, and add it to the parser
+        action_class = self._pop_action_class(kwargs)
+        action = action_class(**kwargs)
+        return self._add_action(action)
+
+    def _add_action(self, action):
+        # resolve any conflicts
+        self._check_conflict(action)
+
+        # add to optional or positional list
+        if action.option_strings:
+            self._optional_actions_list.append(action)
+        else:
+            self._positional_actions_list.append(action)
+            self._positional_actions_full_list.append(action)
+        action.container = self
+
+        # index the action by any option strings it has
+        for option_string in action.option_strings:
+            self._option_strings[option_string] = action
+
+        # return the created action
+        return action
+
+    def _add_container_actions(self, container):
+        for action in container._optional_actions_list:
+            self._add_action(action)
+        for action in container._positional_actions_list:
+            self._add_action(action)
+
+    def _get_positional_kwargs(self, dest, **kwargs):
+        # make sure required is not specified
+        if 'required' in kwargs:
+            msg = _("'required' is an invalid argument for positionals")
+            raise TypeError(msg)
+        
+        # return the keyword arguments with no option strings
+        return dict(kwargs, dest=dest, option_strings=[])
+
+    def _get_optional_kwargs(self, *args, **kwargs):
+        # determine short and long option strings
+        option_strings = []
+        long_option_strings = []
+        for option_string in args:
+            # error on one-or-fewer-character option strings
+            if len(option_string) < 2:
+                msg = _('invalid option string %r: '
+                        'must be at least two characters long')
+                raise ValueError(msg % option_string)
+
+            # error on strings that don't start with an appropriate prefix
+            if not option_string[0] in self.prefix_chars:
+                msg = _('invalid option string %r: '
+                        'must start with a character %r')
+                tup = option_string, self.prefix_chars
+                raise ValueError(msg % tup)
+
+            # error on strings that are all prefix characters
+            if not (set(option_string) - set(self.prefix_chars)):
+                msg = _('invalid option string %r: '
+                        'must contain characters other than %r')
+                tup = option_string, self.prefix_chars
+                raise ValueError(msg % tup)
+
+            # strings starting with two prefix characters are long options
+            option_strings.append(option_string)            
+            if option_string[0] in self.prefix_chars:
+                if option_string[1] in self.prefix_chars:
+                    long_option_strings.append(option_string)
+
+        # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
+        dest = kwargs.pop('dest', None)
+        if dest is None:
+            if long_option_strings:
+                dest_option_string = long_option_strings[0]
+            else:
+                dest_option_string = option_strings[0]
+            dest = dest_option_string.lstrip(self.prefix_chars)
+            dest = dest.replace('-', '_')
+
+        # return the updated keyword arguments
+        return dict(kwargs, dest=dest, option_strings=option_strings)
+
+    def _pop_action_class(self, kwargs, default=None):
+        action = kwargs.pop('action', default)
+        return self._registry_get('action', action, action)
+
+    def _get_handler(self):
+        # determine function from conflict handler string
+        handler_func_name = '_handle_conflict_%s' % self.conflict_handler
+        try:
+            return getattr(self, handler_func_name)
+        except AttributeError:
+            msg = _('invalid conflict_resolution value: %r')
+            raise ValueError(msg % self.conflict_handler)
+
+    def _check_conflict(self, action):
+
+        # find all options that conflict with this option        
+        confl_optionals = []
+        for option_string in action.option_strings:
+            if option_string in self._option_strings:
+                confl_optional = self._option_strings[option_string]
+                confl_optionals.append((option_string, confl_optional))
+
+        # resolve any conflicts
+        if confl_optionals:
+            conflict_handler = self._get_handler()
+            conflict_handler(action, confl_optionals)
+
+    def _handle_conflict_error(self, action, conflicting_actions):
+        message = _('conflicting option string(s): %s')
+        conflict_string = ', '.join(option_string
+                                    for option_string, action
+                                    in conflicting_actions)
+        raise ArgumentError(action, message % conflict_string)
+
+    def _handle_conflict_resolve(self, action, conflicting_actions):
+
+        # remove all conflicting options        
+        for option_string, action in conflicting_actions:
+            
+            # remove the conflicting option
+            action.option_strings.remove(option_string)
+            self._option_strings.pop(option_string, None)
+
+            # if the option now has no option string, remove it from the
+            # container holding it
+            if not action.option_strings:
+                action.container._optional_actions_list.remove(action)
+
+
+class _ArgumentGroup(_ActionsContainer):
+
+    def __init__(self, container, title=None, description=None, **kwargs):
+        # add any missing keyword arguments by checking the container
+        update = kwargs.setdefault
+        update('conflict_handler', container.conflict_handler)
+        update('prefix_chars', container.prefix_chars)
+        update('argument_default', container.argument_default)
+        super_init = super(_ArgumentGroup, self).__init__
+        super_init(description=description, **kwargs)
+        
+        self.title = title
+        self._registries = container._registries
+        self._positional_actions_full_list = container._positional_actions_full_list
+        self._option_strings = container._option_strings
+        self._defaults = container._defaults
+
+
+class ArgumentParser(_AttributeHolder, _ActionsContainer):
+
+    def __init__(self,
+                 prog=None,
+                 usage=None,
+                 description=None,
+                 epilog=None,
+                 version=None,
+                 parents=[],
+                 formatter_class=HelpFormatter,
+                 prefix_chars='-',
+                 argument_default=None,
+                 conflict_handler='error',
+                 add_help=True):
+
+        superinit = super(ArgumentParser, self).__init__
+        superinit(description=description,
+                  prefix_chars=prefix_chars,
+                  argument_default=argument_default,
+                  conflict_handler=conflict_handler)
+
+        # default setting for prog
+        if prog is None:
+            prog = _os.path.basename(_sys.argv[0])
+
+        self.prog = prog
+        self.usage = usage
+        self.epilog = epilog
+        self.version = version
+        self.formatter_class = formatter_class
+        self.add_help = add_help
+
+        self._argument_group_class = _ArgumentGroup
+        self._has_subparsers = False
+        self._argument_groups = []
+
+        # register types
+        def identity(string):
+            return string
+        self.register('type', None, identity)
+
+        # add help and version arguments if necessary
+        # (using explicit default to override global argument_default)
+        if self.add_help:
+            self.add_argument(
+                '-h', '--help', action='help', default=SUPPRESS,
+                help=_('show this help message and exit'))
+        if self.version:
+            self.add_argument(
+                '-v', '--version', action='version', default=SUPPRESS,
+                help=_("show program's version number and exit"))
+
+        # add parent arguments and defaults
+        for parent in parents:
+            self._add_container_actions(parent)
+            try:
+                defaults = parent._defaults
+            except AttributeError:
+                pass
+            else:
+                self._defaults.update(defaults)
+
+        # determines whether an "option" looks like a negative number
+        self._negative_number_matcher = _re.compile(r'^-\d+|-\d*.\d+$')
+                
+
+    # =======================
+    # Pretty __repr__ methods
+    # =======================
+
+    def _get_kwargs(self):
+        names = [
+            'prog',
+            'usage',
+            'description',
+            'version',
+            'formatter_class',
+            'conflict_handler',
+            'add_help',
+        ]
+        return [(name, getattr(self, name)) for name in names]
+
+    # ==================================
+    # Optional/Positional adding methods
+    # ==================================
+
+    def add_argument_group(self, *args, **kwargs):
+        group = self._argument_group_class(self, *args, **kwargs)
+        self._argument_groups.append(group)
+        return group
+
+    def add_subparsers(self, **kwargs):
+        if self._has_subparsers:
+            self.error(_('cannot have multiple subparser arguments'))
+        
+        # add the parser class to the arguments if it's not present
+        kwargs.setdefault('parser_class', type(self))
+
+        # prog defaults to the usage message of this parser, skipping
+        # optional arguments and with no "usage:" prefix
+        if kwargs.get('prog') is None:
+            formatter = self._get_formatter()
+            formatter.add_usage(self.usage, [],
+                                self._get_positional_actions(), '')
+            kwargs['prog'] = formatter.format_help().strip()
+
+        # create the parsers action and add it to the positionals list
+        parsers_class = self._pop_action_class(kwargs, 'parsers')
+        action = parsers_class(option_strings=[], **kwargs)
+        self._positional_actions_list.append(action)
+        self._positional_actions_full_list.append(action)
+        self._has_subparsers = True
+
+        # return the created parsers action
+        return action
+
+    def _add_container_actions(self, container):
+        super(ArgumentParser, self)._add_container_actions(container)
+        try:
+            groups = container._argument_groups
+        except AttributeError:
+            pass
+        else:
+            for group in groups:
+                new_group = self.add_argument_group(
+                    title=group.title,
+                    description=group.description,
+                    conflict_handler=group.conflict_handler)
+                new_group._add_container_actions(group)
+
+    def _get_optional_actions(self):
+        actions = []
+        actions.extend(self._optional_actions_list)
+        for argument_group in self._argument_groups:
+            actions.extend(argument_group._optional_actions_list)
+        return actions
+
+    def _get_positional_actions(self):
+        return list(self._positional_actions_full_list)
+
+
+    # =====================================
+    # Command line argument parsing methods
+    # =====================================
+
+    def parse_args(self, args=None, namespace=None):
+        # args default to the system args
+        if args is None:
+            args = _sys.argv[1:]
+
+        # default Namespace built from parser defaults
+        if namespace is None:
+            namespace = Namespace()
+            
+        # add any action defaults that aren't present
+        optional_actions = self._get_optional_actions()
+        positional_actions = self._get_positional_actions()
+        for action in optional_actions + positional_actions:
+            if action.dest is not SUPPRESS:
+                if not hasattr(namespace, action.dest):
+                    if action.default is not SUPPRESS:
+                        default = action.default
+                        if isinstance(action.default, basestring):
+                            default = self._get_value(action, default)
+                        setattr(namespace, action.dest, default)
+
+        # add any parser defaults that aren't present
+        for dest, value in self._defaults.iteritems():
+            if not hasattr(namespace, dest):
+                setattr(namespace, dest, value)
+            
+        # parse the arguments and exit if there are any errors
+        try:
+            result = self._parse_args(args, namespace)
+        except ArgumentError, err:
+            self.error(str(err))
+
+        # make sure all required optionals are present
+        for action in self._get_optional_actions():
+            if action.required:
+                if getattr(result, action.dest, None) is None:
+                    opt_strs = '/'.join(action.option_strings)
+                    msg = _('option %s is required' % opt_strs)
+                    self.error(msg)
+
+        # return the parsed arguments                    
+        return result
+
+    def _parse_args(self, arg_strings, namespace):            
+
+        # find all option indices, and determine the arg_string_pattern
+        # which has an 'O' if there is an option at an index,
+        # an 'A' if there is an argument, or a '-' if there is a '--'
+        option_string_indices = {}
+        arg_string_pattern_parts = []
+        arg_strings_iter = iter(arg_strings)
+        for i, arg_string in enumerate(arg_strings_iter):
+
+            # all args after -- are non-options
+            if arg_string == '--':
+                arg_string_pattern_parts.append('-')
+                for arg_string in arg_strings_iter:
+                    arg_string_pattern_parts.append('A')
+
+            # otherwise, add the arg to the arg strings
+            # and note the index if it was an option
+            else:
+                option_tuple = self._parse_optional(arg_string)
+                if option_tuple is None:
+                    pattern = 'A'
+                else:
+                    option_string_indices[i] = option_tuple
+                    pattern = 'O'
+                arg_string_pattern_parts.append(pattern)
+
+        # join the pieces together to form the pattern
+        arg_strings_pattern = ''.join(arg_string_pattern_parts)
+
+        # converts arg strings to the appropriate and then takes the action
+        def take_action(action, argument_strings, option_string=None):
+            argument_values = self._get_values(action, argument_strings)
+            # take the action if we didn't receive a SUPPRESS value
+            # (e.g. from a default)            
+            if argument_values is not SUPPRESS:
+                action(self, namespace, argument_values, option_string)
+
+        # function to convert arg_strings into an optional action
+        def consume_optional(start_index):
+            
+            # determine the optional action and parse any explicit
+            # argument out of the option string
+            option_tuple = option_string_indices[start_index]
+            action, option_string, explicit_arg = option_tuple
+
+            # loop because single-dash options can be chained
+            # (e.g. -xyz is the same as -x -y -z if no args are required)
+            match_argument = self._match_argument
+            action_tuples = []
+            while True:
+
+                # if we found no optional action, raise an error
+                if action is None:
+                    self.error(_('no such option: %s') % option_string)
+
+                # if there is an explicit argument, try to match the
+                # optional's string arguments to only this
+                if explicit_arg is not None:
+                    arg_count = match_argument(action, 'A')
+
+                    # if the action is a single-dash option and takes no
+                    # arguments, try to parse more single-dash options out
+                    # of the tail of the option string
+                    chars = self.prefix_chars
+                    if arg_count == 0 and option_string[1] not in chars:
+                        action_tuples.append((action, [], option_string))
+                        parse_optional = self._parse_optional
+                        for char in self.prefix_chars:
+                            option_string = char + explicit_arg
+                            option_tuple = parse_optional(option_string)
+                            if option_tuple[0] is not None:
+                                break
+                        else:
+                            msg = _('ignored explicit argument %r')
+                            raise ArgumentError(action, msg % explicit_arg)
+
+                        # set the action, etc. for the next loop iteration
+                        action, option_string, explicit_arg = option_tuple
+
+                    # if the action expect exactly one argument, we've
+                    # successfully matched the option; exit the loop
+                    elif arg_count == 1:
+                        stop = start_index + 1
+                        args = [explicit_arg]
+                        action_tuples.append((action, args, option_string))
+                        break
+
+                    # error if a double-dash option did not use the
+                    # explicit argument
+                    else:
+                        msg = _('ignored explicit argument %r')
+                        raise ArgumentError(action, msg % explicit_arg)
+                
+                # if there is no explicit argument, try to match the
+                # optional's string arguments with the following strings
+                # if successful, exit the loop
+                else:
+                    start = start_index + 1
+                    selected_patterns = arg_strings_pattern[start:]
+                    arg_count = match_argument(action, selected_patterns)
+                    stop = start + arg_count
+                    args = arg_strings[start:stop]
+                    action_tuples.append((action, args, option_string))
+                    break
+
+            # add the Optional to the list and return the index at which
+            # the Optional's string args stopped
+            assert action_tuples
+            for action, args, option_string in action_tuples:
+                take_action(action, args, option_string)
+            return stop
+
+        # the list of Positionals left to be parsed; this is modified
+        # by consume_positionals()
+        positionals = self._get_positional_actions()
+
+        # function to convert arg_strings into positional actions
+        def consume_positionals(start_index):
+            # match as many Positionals as possible
+            match_partial = self._match_arguments_partial
+            selected_pattern = arg_strings_pattern[start_index:]
+            arg_counts = match_partial(positionals, selected_pattern)
+
+            # slice off the appropriate arg strings for each Positional
+            # and add the Positional and its args to the list
+            for action, arg_count in zip(positionals, arg_counts):
+                args = arg_strings[start_index: start_index + arg_count]
+                start_index += arg_count
+                take_action(action, args)
+
+            # slice off the Positionals that we just parsed and return the
+            # index at which the Positionals' string args stopped
+            positionals[:] = positionals[len(arg_counts):]
+            return start_index
+
+        # consume Positionals and Optionals alternately, until we have
+        # passed the last option string
+        start_index = 0
+        if option_string_indices:
+            max_option_string_index = max(option_string_indices)
+        else:
+            max_option_string_index = -1
+        while start_index <= max_option_string_index:
+            
+            # consume any Positionals preceding the next option
+            next_option_string_index = min(
+                index
+                for index in option_string_indices
+                if index >= start_index)
+            if start_index != next_option_string_index:
+                positionals_end_index = consume_positionals(start_index)
+
+                # only try to parse the next optional if we didn't consume
+                # the option string during the positionals parsing
+                if positionals_end_index > start_index:
+                    start_index = positionals_end_index
+                    continue
+                else:
+                    start_index = positionals_end_index
+
+            # if we consumed all the positionals we could and we're not
+            # at the index of an option string, there were unparseable
+            # arguments
+            if start_index not in option_string_indices:
+                msg = _('extra arguments found: %s')
+                extras = arg_strings[start_index:next_option_string_index]
+                self.error(msg % ' '.join(extras))
+
+            # consume the next optional and any arguments for it
+            start_index = consume_optional(start_index)
+
+        # consume any positionals following the last Optional
+        stop_index = consume_positionals(start_index)
+
+        # if we didn't consume all the argument strings, there were too
+        # many supplied
+        if stop_index != len(arg_strings):
+            extras = arg_strings[stop_index:]
+            self.error(_('extra arguments found: %s') % ' '.join(extras))
+
+        # if we didn't use all the Positional objects, there were too few
+        # arg strings supplied.
+        if positionals:
+            self.error(_('too few arguments'))
+
+        # return the updated namespace
+        return namespace
+
+    def _match_argument(self, action, arg_strings_pattern):
+        # match the pattern for this action to the arg strings
+        nargs_pattern = self._get_nargs_pattern(action)
+        match = _re.match(nargs_pattern, arg_strings_pattern)
+
+        # raise an exception if we weren't able to find a match        
+        if match is None:
+            nargs_errors = {
+                None:_('expected one argument'),
+                OPTIONAL:_('expected at most one argument'),
+                ONE_OR_MORE:_('expected at least one argument')
+            }
+            default = _('expected %s argument(s)') % action.nargs
+            msg = nargs_errors.get(action.nargs, default)
+            raise ArgumentError(action, msg)
+
+        # return the number of arguments matched
+        return len(match.group(1))
+
+    def _match_arguments_partial(self, actions, arg_strings_pattern):
+        # progressively shorten the actions list by slicing off the
+        # final actions until we find a match
+        result = []
+        for i in xrange(len(actions), 0, -1):
+            actions_slice = actions[:i]
+            pattern = ''.join(self._get_nargs_pattern(action)
+                              for action in actions_slice)
+            match = _re.match(pattern, arg_strings_pattern)
+            if match is not None:
+                result.extend(len(string) for string in match.groups())
+                break
+
+        # return the list of arg string counts
+        return result
+    
+    def _parse_optional(self, arg_string):
+        # if it doesn't start with a prefix, it was meant to be positional
+        if not arg_string[0] in self.prefix_chars:
+            return None
+        
+        # if it's just dashes, it was meant to be positional
+        if not arg_string.strip('-'):
+            return None
+
+        # if the option string is present in the parser, return the action
+        if arg_string in self._option_strings:
+            action = self._option_strings[arg_string]
+            return action, arg_string, None
+
+        # search through all possible prefixes of the option string
+        # and all actions in the parser for possible interpretations
+        option_tuples = []
+        prefix_tuples = self._get_option_prefix_tuples(arg_string)
+        for option_string in self._option_strings:
+            for option_prefix, explicit_arg in prefix_tuples:
+                if option_string.startswith(option_prefix):
+                    action = self._option_strings[option_string]
+                    tup = action, option_string, explicit_arg
+                    option_tuples.append(tup)
+                    break
+
+        # if multiple actions match, the option string was ambiguous
+        if len(option_tuples) > 1:
+            options = ', '.join(opt_str for _, opt_str, _ in option_tuples)
+            tup = arg_string, options
+            self.error(_('ambiguous option: %s could match %s') % tup)
+
+        # if exactly one action matched, this segmentation is good,
+        # so return the parsed action
+        elif len(option_tuples) == 1:
+            option_tuple, = option_tuples
+            return option_tuple
+
+        # if it was not found as an option, but it looks like a negative
+        # number, it was meant to be positional
+        if self._negative_number_matcher.match(arg_string):
+            return None
+
+        # it was meant to be an optional but there is no such option
+        # in this parser (though it might be a valid option in a subparser)
+        return None, arg_string, None
+
+    def _get_option_prefix_tuples(self, option_string):
+        result = []
+        
+        # option strings starting with two prefix characters are only
+        # split at the '='
+        chars = self.prefix_chars
+        if option_string[0] in chars and option_string[1] in chars:
+            if '=' in option_string:
+                option_prefix, explicit_arg = option_string.split('=', 1)
+            else:
+                option_prefix = option_string
+                explicit_arg = None
+            tup = option_prefix, explicit_arg
+            result.append(tup)
+
+        # option strings starting with a single prefix character are
+        # split at all indices
+        else:
+            for first_index, char in enumerate(option_string):
+                if char not in self.prefix_chars:
+                    break
+            for i in xrange(len(option_string), first_index, -1):
+                tup = option_string[:i], option_string[i:] or None
+                result.append(tup)
+
+        # return the collected prefix tuples
+        return result                
+
+    def _get_nargs_pattern(self, action):
+        # in all examples below, we have to allow for '--' args
+        # which are represented as '-' in the pattern
+        nargs = action.nargs
+        
+        # the default (None) is assumed to be a single argument
+        if nargs is None:
+            nargs_pattern = '(-*A-*)'
+
+        # allow zero or one arguments
+        elif nargs == OPTIONAL:
+            nargs_pattern = '(-*A?-*)'
+
+        # allow zero or more arguments
+        elif nargs == ZERO_OR_MORE:
+            nargs_pattern = '(-*[A-]*)'
+
+        # allow one or more arguments
+        elif nargs == ONE_OR_MORE:
+            nargs_pattern = '(-*A[A-]*)'
+
+        # allow one argument followed by any number of options or arguments
+        elif nargs is PARSER:
+            nargs_pattern = '(-*A[-AO]*)'
+
+        # all others should be integers            
+        else:
+            nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs)
+
+        # if this is an optional action, -- is not allowed        
+        if action.option_strings:
+            nargs_pattern = nargs_pattern.replace('-*', '')
+            nargs_pattern = nargs_pattern.replace('-', '')
+
+        # return the pattern
+        return nargs_pattern
+
+    # ========================
+    # Value conversion methods
+    # ========================
+
+    def _get_values(self, action, arg_strings):
+        # for everything but PARSER args, strip out '--'
+        if action.nargs is not PARSER:
+            arg_strings = [s for s in arg_strings if s != '--']
+        
+        # optional argument produces a default when not present
+        if not arg_strings and action.nargs == OPTIONAL:
+            if action.option_strings:
+                value = action.const
+            else:
+                value = action.default
+            if isinstance(value, basestring):
+                value = self._get_value(action, value)
+                self._check_value(action, value)
+
+        # when nargs='*' on a positional, if there were no command-line
+        # args, use the default if it is anything other than None
+        elif (not arg_strings and action.nargs == ZERO_OR_MORE and
+              not action.option_strings):
+            if action.default is not None:
+                value = action.default
+            else:
+                value = arg_strings
+            self._check_value(action, value)
+        
+        # single argument or optional argument produces a single value
+        elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:
+            arg_string, = arg_strings
+            value = self._get_value(action, arg_string)
+            self._check_value(action, value)
+
+        # PARSER arguments convert all values, but check only the first
+        elif action.nargs is PARSER:
+            value = list(self._get_value(action, v) for v in arg_strings)
+            self._check_value(action, value[0])
+
+        # all other types of nargs produce a list
+        else:
+            value = list(self._get_value(action, v) for v in arg_strings)
+            for v in value:
+                self._check_value(action, v)
+
+        # return the converted value            
+        return value
+
+    def _get_value(self, action, arg_string):
+        type_func = self._registry_get('type', action.type, action.type)
+        if not callable(type_func):
+            msg = _('%r is not callable')
+            raise ArgumentError(action, msg % type_func)
+        
+        # convert the value to the appropriate type
+        try:
+            result = type_func(arg_string)
+
+        # TypeErrors or ValueErrors indicate errors
+        except (TypeError, ValueError):
+            name = getattr(action.type, '__name__', repr(action.type))
+            msg = _('invalid %s value: %r')
+            raise ArgumentError(action, msg % (name, arg_string))
+
+        # return the converted value
+        return result
+
+    def _check_value(self, action, value):
+        # converted value must be one of the choices (if specified)
+        if action.choices is not None and value not in action.choices:
+            tup = value, ', '.join(map(repr, action.choices))
+            msg = _('invalid choice: %r (choose from %s)') % tup
+            raise ArgumentError(action, msg)
+
+        
+
+    # =======================
+    # Help-formatting methods
+    # =======================
+
+    def format_usage(self):
+        formatter = self._get_formatter()
+        formatter.add_usage(self.usage,
+                            self._get_optional_actions(),
+                            self._get_positional_actions())
+        return formatter.format_help()
+
+    def format_help(self):
+        formatter = self._get_formatter()
+
+        # usage
+        formatter.add_usage(self.usage,
+                            self._get_optional_actions(),
+                            self._get_positional_actions())
+
+        # description        
+        formatter.add_text(self.description)
+
+        # positionals
+        formatter.start_section(_('positional arguments'))
+        formatter.add_arguments(self._positional_actions_list)
+        formatter.end_section()
+
+        # optionals
+        formatter.start_section(_('optional arguments'))
+        formatter.add_arguments(self._optional_actions_list)
+        formatter.end_section()
+
+        # user-defined groups
+        for argument_group in self._argument_groups:
+            formatter.start_section(argument_group.title)
+            formatter.add_text(argument_group.description)
+            formatter.add_arguments(argument_group._positional_actions_list)
+            formatter.add_arguments(argument_group._optional_actions_list)
+            formatter.end_section()
+
+        # epilog
+        formatter.add_text(self.epilog)
+
+        # determine help from format above
+        return formatter.format_help()
+
+    def format_version(self):
+        formatter = self._get_formatter()
+        formatter.add_text(self.version)
+        return formatter.format_help()
+
+    def _get_formatter(self):
+        return self.formatter_class(prog=self.prog)
+
+    # =====================
+    # Help-printing methods
+    # =====================
+
+    def print_usage(self, file=None):
+        self._print_message(self.format_usage(), file)
+
+    def print_help(self, file=None):
+        self._print_message(self.format_help(), file)
+
+    def print_version(self, file=None):
+        self._print_message(self.format_version(), file)
+
+    def _print_message(self, message, file=None):
+        if message:
+            if file is None:
+                file = _sys.stderr
+            file.write(message)
+
+
+    # ===============
+    # Exiting methods
+    # ===============
+
+    def exit(self, status=0, message=None):
+        if message:
+            _sys.stderr.write(message)
+        _sys.exit(status)
+
+    def error(self, message):
+        """error(message: string)
+
+        Prints a usage message incorporating the message to stderr and
+        exits.
+        
+        If you override this in a subclass, it should not return -- it
+        should either exit or raise an exception.
+        """
+        self.print_usage(_sys.stderr)
+        self.exit(2, _('%s: error: %s\n') % (self.prog, message))

IPython/frontend/tests/test_asyncfrontendbase.py

@@ -0,0 +1,155
+# encoding: utf-8
+
+"""This file contains unittests for the frontendbase module."""
+
+__docformat__ = "restructuredtext en"
+
+#---------------------------------------------------------------------------
+#  Copyright (C) 2008  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 unittest
+
+try:
+    from IPython.frontend.asyncfrontendbase import AsyncFrontEndBase
+    from IPython.frontend import frontendbase 
+    from IPython.kernel.engineservice import EngineService
+except ImportError:
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
+
+from IPython.testing.decorators import skip
+
+class FrontEndCallbackChecker(AsyncFrontEndBase):
+    """FrontEndBase subclass for checking callbacks"""
+    def __init__(self, engine=None, history=None):
+        super(FrontEndCallbackChecker, self).__init__(engine=engine, 
+                                                    history=history)
+        self.updateCalled = False
+        self.renderResultCalled = False
+        self.renderErrorCalled = False
+   
+    def update_cell_prompt(self, result, blockID=None):
+        self.updateCalled = True
+        return result
+   
+    def render_result(self, result):
+        self.renderResultCalled = True
+        return result
+    
+    
+    def render_error(self, failure):
+        self.renderErrorCalled = True
+        return failure
+    
+
+
+    
+class TestAsyncFrontendBase(unittest.TestCase):
+    def setUp(self):
+        """Setup the EngineService and FrontEndBase"""
+        
+        self.fb = FrontEndCallbackChecker(engine=EngineService())
+    
+    def test_implements_IFrontEnd(self):
+        assert(frontendbase.IFrontEnd.implementedBy(
+                                    AsyncFrontEndBase))
+    
+    def test_is_complete_returns_False_for_incomplete_block(self):
+        """"""
+        
+        block = """def test(a):"""
+        
+        assert(self.fb.is_complete(block) == False)
+    
+    def test_is_complete_returns_True_for_complete_block(self):
+        """"""
+        
+        block = """def test(a): pass"""
+            
+        assert(self.fb.is_complete(block))
+        
+        block = """a=3"""
+        
+        assert(self.fb.is_complete(block))
+    
+    def test_blockID_added_to_result(self):
+        block = """3+3"""
+        
+        d = self.fb.execute(block, blockID='TEST_ID')
+        
+        d.addCallback(self.checkBlockID, expected='TEST_ID')
+    
+    def test_blockID_added_to_failure(self):
+        block = "raise Exception()"
+        
+        d = self.fb.execute(block,blockID='TEST_ID')
+        d.addErrback(self.checkFailureID, expected='TEST_ID')
+    
+    def checkBlockID(self, result, expected=""):
+        assert(result['blockID'] == expected)
+    
+    
+    def checkFailureID(self, failure, expected=""):
+        assert(failure.blockID == expected)
+    
+    
+    def test_callbacks_added_to_execute(self):
+        """test that
+        update_cell_prompt
+        render_result
+        
+        are added to execute request
+        """
+        
+        d = self.fb.execute("10+10")
+        d.addCallback(self.checkCallbacks)
+    
+    def checkCallbacks(self, result):
+        assert(self.fb.updateCalled)
+        assert(self.fb.renderResultCalled)
+    
+    @skip("This test fails and lead to an unhandled error in a Deferred.")
+    def test_error_callback_added_to_execute(self):
+        """test that render_error called on execution error"""
+        
+        d = self.fb.execute("raise Exception()")
+        d.addCallback(self.checkRenderError)
+    
+    def checkRenderError(self, result):
+        assert(self.fb.renderErrorCalled)
+    
+    def test_history_returns_expected_block(self):
+        """Make sure history browsing doesn't fail"""
+        
+        blocks = ["a=1","a=2","a=3"]
+        for b in blocks:
+            d = self.fb.execute(b)
+        
+        # d is now the deferred for the last executed block
+        d.addCallback(self.historyTests, blocks)
+        
+    
+    def historyTests(self, result, blocks):
+        """historyTests"""
+        
+        assert(len(blocks) >= 3)
+        assert(self.fb.get_history_previous("") == blocks[-2])
+        assert(self.fb.get_history_previous("") == blocks[-3])
+        assert(self.fb.get_history_next() == blocks[-2])
+    
+    
+    def test_history_returns_none_at_startup(self):
+        """test_history_returns_none_at_startup"""
+        
+        assert(self.fb.get_history_previous("")==None)
+        assert(self.fb.get_history_next()==None)
+    
+    

IPython/kernel/core/tests/test_interpreter.py

@@ -0,0 +1,26
+# encoding: utf-8
+
+"""This file contains unittests for the interpreter.py module."""
+
+__docformat__ = "restructuredtext en"
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008  The IPython Development Team                           
+#                                                                             
+#  Distributed under the terms of the BSD License.  The full license is in    
+#  the file COPYING, distributed as part of this software.                    
+#-----------------------------------------------------------------------------
+                                                                              
+#-----------------------------------------------------------------------------
+# Imports                                                                     
+#-----------------------------------------------------------------------------
+
+from IPython.kernel.core.interpreter import Interpreter
+
+def test_unicode():
+    """ Test unicode handling with the interpreter.
+    """
+    i = Interpreter()
+    i.execute_python(u'print "ù"')
+    i.execute_python('print "ù"')
+

IPython/testing/iptest.py

@@ -0,0 +1,53
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""IPython Test Suite Runner.
+"""
+
+import sys
+import warnings
+
+from nose.core import TestProgram
+import nose.plugins.builtin
+
+from IPython.testing.plugin.ipdoctest import IPythonDoctest
+
+def main():
+    """Run the IPython test suite.
+    """
+
+    warnings.filterwarnings('ignore', 
+        'This will be removed soon.  Use IPython.testing.util instead')
+
+    
+    # construct list of plugins, omitting the existing doctest plugin
+    plugins = [IPythonDoctest()]
+    for p in nose.plugins.builtin.plugins:
+        plug = p()
+        if plug.name == 'doctest':
+            continue
+
+        #print 'adding plugin:',plug.name  # dbg
+        plugins.append(plug)
+
+    argv = sys.argv + ['--doctest-tests','--doctest-extension=txt',
+                       '--detailed-errors',
+                       
+                       # We add --exe because of setuptools' imbecility (it
+                       # blindly does chmod +x on ALL files).  Nose does the
+                       # right thing and it tries to avoid executables,
+                       # setuptools unfortunately forces our hand here.  This
+                       # has been discussed on the distutils list and the
+                       # setuptools devs refuse to fix this problem!
+                       '--exe',
+                       ]
+
+    has_ip = False
+    for arg in sys.argv:
+        if 'IPython' in arg:
+            has_ip = True
+            break
+
+    if not has_ip:
+        argv.append('IPython')
+
+    TestProgram(argv=argv,plugins=plugins)

IPython/testing/tests/test_decorators.py

@@ -0,0 +1,161
+"""Tests for the decorators we've created for IPython.
+"""
+
+# Module imports
+# Std lib
+import inspect
+import sys
+
+# Third party
+import nose.tools as nt
+
+# Our own
+from IPython.testing import decorators as dec
+
+
+#-----------------------------------------------------------------------------
+# Utilities
+
+# Note: copied from OInspect, kept here so the testing stuff doesn't create
+# circular dependencies and is easier to reuse.
+def getargspec(obj):
+    """Get the names and default values of a function's arguments.
+
+    A tuple of four things is returned: (args, varargs, varkw, defaults).
+    'args' is a list of the argument names (it may contain nested lists).
+    'varargs' and 'varkw' are the names of the * and ** arguments or None.
+    'defaults' is an n-tuple of the default values of the last n arguments.
+
+    Modified version of inspect.getargspec from the Python Standard
+    Library."""
+
+    if inspect.isfunction(obj):
+        func_obj = obj
+    elif inspect.ismethod(obj):
+        func_obj = obj.im_func
+    else:
+        raise TypeError, 'arg is not a Python function'
+    args, varargs, varkw = inspect.getargs(func_obj.func_code)
+    return args, varargs, varkw, func_obj.func_defaults
+
+#-----------------------------------------------------------------------------
+# Testing functions
+
[e-mail]
+def test_deliberately_broken():
+    """A deliberately broken test - we want to skip this one."""
+    1/0
+
[e-mail]('foo')
+def test_deliberately_broken2():
+    """Another deliberately broken test - we want to skip this one."""
+    1/0
+
+
+# Verify that we can correctly skip the doctest for a function at will, but
+# that the docstring itself is NOT destroyed by the decorator.
[e-mail]_doctest
+def doctest_bad(x,y=1,**k):
+    """A function whose doctest we need to skip.
+
+    >>> 1+1
+    3
+    """
+    print 'x:',x
+    print 'y:',y
+    print 'k:',k
+
+
+def call_doctest_bad():
+    """Check that we can still call the decorated functions.
+    
+    >>> doctest_bad(3,y=4)
+    x: 3
+    y: 4
+    k: {}
+    """
+    pass
+
+
+def test_skip_dt_decorator():
+    """Doctest-skipping decorator should preserve the docstring.
+    """
+    # Careful: 'check' must be a *verbatim* copy of the doctest_bad docstring!
+    check = """A function whose doctest we need to skip.
+
+    >>> 1+1
+    3
+    """
+    # Fetch the docstring from doctest_bad after decoration.
+    val = doctest_bad.__doc__
+    
+    assert check==val,"doctest_bad docstrings don't match"
+
+# Doctest skipping should work for class methods too
+class foo(object):
+    """Foo
+
+    Example:
+
+    >>> 1+1
+    2
+    """
+
+    @dec.skip_doctest
+    def __init__(self,x):
+        """Make a foo.
+
+        Example:
+
+        >>> f = foo(3)
+        junk
+        """
+        print 'Making a foo.'
+        self.x = x
+        
+    @dec.skip_doctest
+    def bar(self,y):
+        """Example:
+
+        >>> f = foo(3)
+        >>> f.bar(0)
+        boom!
+        >>> 1/0
+        bam!
+        """
+        return 1/y
+
+    def baz(self,y):
+        """Example:
+
+        >>> f = foo(3)
+        Making a foo.
+        >>> f.baz(3)
+        True
+        """
+        return self.x==y
+
+
+
+def test_skip_dt_decorator2():
+    """Doctest-skipping decorator should preserve function signature.
+    """
+    # Hardcoded correct answer
+    dtargs = (['x', 'y'], None, 'k', (1,))
+    # Introspect out the value
+    dtargsr = getargspec(doctest_bad)
+    assert dtargsr==dtargs, \
+           "Incorrectly reconstructed args for doctest_bad: %s" % (dtargsr,)
+
+
[e-mail]_linux
+def test_linux():
+    nt.assert_not_equals(sys.platform,'linux2',"This test can't run under linux")
+
[e-mail]_win32
+def test_win32():
+    nt.assert_not_equals(sys.platform,'win32',"This test can't run under windows")
+
[e-mail]_osx
+def test_osx():
+    nt.assert_not_equals(sys.platform,'darwin',"This test can't run under osx")

IPython/tests/test_genutils.py

@@ -0,0 +1,32
+# encoding: utf-8
+
+"""Tests for genutils.py"""
+
+__docformat__ = "restructuredtext en"
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+from IPython import genutils
+
+
+def test_get_home_dir():
+    """Make sure we can get the home directory."""
+    home_dir = genutils.get_home_dir()
+
+def test_get_ipython_dir():
+    """Make sure we can get the ipython directory."""
+    ipdir = genutils.get_ipython_dir()
+
+def test_get_security_dir():
+    """Make sure we can get the ipython/security directory."""
+    sdir = genutils.get_security_dir()
+    
  No newline at end of file

IPython/tests/test_magic.py

@@ -0,0 +1,21
+""" Tests for various magic functions
+
+Needs to be run by nose (to make ipython session available)
+
+"""
+def test_rehashx():
+    # clear up everything
+    _ip.IP.alias_table.clear()
+    del _ip.db['syscmdlist']
+    
+    _ip.magic('rehashx')
+    # Practically ALL ipython development systems will have more than 10 aliases
+
+    assert len(_ip.IP.alias_table) > 10
+    for key, val in _ip.IP.alias_table.items():
+        # we must strip dots from alias names
+        assert '.' not in key
+
+    # rehashx must fill up syscmdlist
+    scoms = _ip.db['syscmdlist']
+    assert len(scoms) > 10

docs/examples/core/ipython-sh.desktop

@@ -0,0 +1,22
+# If you want ipython to appear in a linux app launcher ("start menu"), install this by doing:
+# sudo desktop-file-install ipython-sh.desktop
+
+[Desktop Entry]
+Comment=Perform shell-like tasks in interactive ipython session
+Exec=ipython -p sh
+GenericName[en_US]=IPython shell mode
+GenericName=IPython shell mode
+Icon=gnome-netstatus-idle
+MimeType=
+Name[en_US]=ipython-sh
+Name=ipython-sh
+Path=
+Categories=Development;Utility;
+StartupNotify=false
+Terminal=true
+TerminalOptions=
+Type=Application
+X-DBUS-ServiceName=
+X-DBUS-StartupType=none
+X-KDE-SubstituteUID=false
+X-KDE-Username=

docs/examples/core/ipython.desktop

@@ -0,0 +1,22
+# If you want ipython to appear in a linux app launcher ("start menu"), install this by doing:
+# sudo desktop-file-install ipython.desktop
+
+[Desktop Entry]
+Comment=Enhanced interactive Python shell
+Exec=ipython
+GenericName[en_US]=IPython
+GenericName=IPython
+Icon=gnome-netstatus-idle
+MimeType=
+Name[en_US]=ipython
+Name=ipython
+Path=
+Categories=Development;Utility;
+StartupNotify=false
+Terminal=true
+TerminalOptions=
+Type=Application
+X-DBUS-ServiceName=
+X-DBUS-StartupType=none
+X-KDE-SubstituteUID=false
+X-KDE-Username=

docs/source/attic/parallel_task_old.txt

@@ -0,0 +1,240
+.. _paralleltask:
+
+==========================
+The IPython task interface
+==========================
+
+.. contents::
+
+The ``Task`` interface to the controller presents the engines as a fault tolerant, dynamic load-balanced system or workers. Unlike the ``MultiEngine`` interface, in the ``Task`` interface, the user have no direct access to individual engines. In some ways, this interface is simpler, but in other ways it is more powerful. Best of all the user can use both of these interfaces at the same time to take advantage or both of their strengths.  When the user can break up the user's work into segments that do not depend on previous execution, the ``Task`` interface is ideal.  But it also has more power and flexibility, allowing the user to guide the distribution of jobs, without having to assign Tasks to engines explicitly.
+
+Starting the IPython controller and engines
+===========================================
+
+To follow along with this tutorial, the user will need to start the IPython
+controller and four IPython engines. The simplest way of doing this is to
+use the ``ipcluster`` command::
+
+	$ ipcluster -n 4
+	
+For more detailed information about starting the controller and engines, see our :ref:`introduction <ip1par>` to using IPython for parallel computing.
+
+The magic here is that this single controller and set of engines is running both the MultiEngine and ``Task`` interfaces simultaneously.
+
+QuickStart Task Farming
+=======================
+
+First, a quick example of how to start running the most basic Tasks.
+The first step is to import the IPython ``client`` module and then create a ``TaskClient`` instance::
+    
+    In [1]: from IPython.kernel import client
+    
+    In [2]: tc = client.TaskClient()
+
+Then the user wrap the commands the user want to run in Tasks::
+
+    In [3]: tasklist = []
+    In [4]: for n in range(1000):
+        ...     tasklist.append(client.Task("a = %i"%n, pull="a"))
+
+The first argument of the ``Task`` constructor is a string, the command to be executed.  The most important optional keyword argument is ``pull``, which can be a string or list of strings, and it specifies the variable names to be saved as results of the ``Task``.
+
+Next, the user need to submit the Tasks to the ``TaskController`` with the ``TaskClient``::
+
+    In [5]: taskids = [ tc.run(t) for t in tasklist ]
+
+This will give the user a list of the TaskIDs used by the controller to keep track of the Tasks and their results.  Now at some point the user are going to want to get those results back.  The ``barrier`` method allows the user to wait for the Tasks to finish running::
+
+    In [6]: tc.barrier(taskids)
+
+This command will block until all the Tasks in ``taskids`` have finished.  Now, the user probably want to look at the user's results::
+
+    In [7]: task_results = [ tc.get_task_result(taskid) for taskid in taskids ]
+
+Now the user have a list of ``TaskResult`` objects, which have the actual result as a dictionary, but also keep track of some useful metadata about the ``Task``::
+
+    In [8]: tr = ``Task``_results[73]
+    
+    In [9]: tr
+    Out[9]: ``TaskResult``[ID:73]:{'a':73}
+    
+    In [10]: tr.engineid
+    Out[10]: 1
+    
+    In [11]: tr.submitted, tr.completed, tr.duration
+    Out[11]: ("2008/03/08 03:41:42", "2008/03/08 03:41:44", 2.12345)
+
+The actual results are stored in a dictionary, ``tr.results``, and a namespace object ``tr.ns`` which accesses the result keys by attribute::
+
+    In [12]: tr.results['a']
+    Out[12]: 73
+    
+    In [13]: tr.ns.a
+    Out[13]: 73
+
+That should cover the basics of running simple Tasks.  There are several more powerful things the user can do with Tasks covered later.  The most useful probably being using a ``MutiEngineClient`` interface to initialize all the engines with the import dependencies necessary to run the user's Tasks.
+
+There are many options for running and managing Tasks. The best way to learn further about the ``Task`` interface is to study the examples in ``docs/examples``. If the user do so and learn a lots about this interface, we encourage the user to expand this documentation about the ``Task`` system.
+
+Overview of the Task System
+===========================
+
+The user's view of the ``Task`` system has three basic objects:  The ``TaskClient``, the ``Task``, and the ``TaskResult``.  The names of these three objects well indicate their role.
+
+The ``TaskClient`` is the user's ``Task`` farming connection to the IPython cluster.  Unlike the ``MultiEngineClient``, the ``TaskControler`` handles all the scheduling and distribution of work, so the ``TaskClient`` has no notion of engines, it just submits Tasks and requests their results.  The Tasks are described as ``Task`` objects, and their results are wrapped in ``TaskResult`` objects.  Thus, there are very few necessary methods for the user to manage.
+
+Inside the task system is a Scheduler object, which assigns tasks to workers.  The default scheduler is a simple FIFO queue.  Subclassing the Scheduler should be easy, just implementing your own priority system.
+
+The TaskClient
+==============
+
+The ``TaskClient`` is the object the user use to connect to the ``Controller`` that is managing the user's Tasks.  It is the analog of the ``MultiEngineClient`` for the standard IPython multiplexing interface.  As with all client interfaces, the first step is to import the IPython Client Module::
+
+    In [1]: from IPython.kernel import client
+
+Just as with the ``MultiEngineClient``, the user create the ``TaskClient`` with a tuple, containing the ip-address and port of the ``Controller``.  the ``client`` module conveniently has the default address of the ``Task`` interface of the controller.  Creating a default ``TaskClient`` object would be done with this::
+
+    In [2]: tc = client.TaskClient(client.default_task_address)
+
+or, if the user want to specify a non default location of the ``Controller``, the user can specify explicitly::
+
+    In [3]: tc = client.TaskClient(("192.168.1.1", 10113))
+
+As discussed earlier, the ``TaskClient`` only has a few basic methods.
+
+ * ``tc.run(task)``
+    ``run`` is the method by which the user submits Tasks.  It takes exactly one argument, a ``Task`` object.  All the advanced control of ``Task`` behavior is handled by properties of the ``Task`` object, rather than the submission command, so they will be discussed later in the `Task`_ section.  ``run`` returns an integer, the ``Task``ID by which the ``Task`` and its results can be tracked and retrieved::
+    
+        In [4]: ``Task``ID = tc.run(``Task``)
+    
+ * ``tc.get_task_result(taskid, block=``False``)``
+    ``get_task_result`` is the method by which results are retrieved.  It takes a single integer argument, the ``Task``ID`` of the result the user wish to retrieve.  ``get_task_result`` also takes a keyword argument ``block``.  ``block`` specifies whether the user actually want to wait for the result.  If ``block`` is false, as it is by default, ``get_task_result`` will return immediately.  If the ``Task`` has completed, it will return the ``TaskResult`` object for that ``Task``.  But if the ``Task`` has not completed, it will return ``None``.  If the user specify ``block=``True``, then ``get_task_result`` will wait for the ``Task`` to complete, and always return the ``TaskResult`` for the requested ``Task``.
+ * ``tc.barrier(taskid(s))``
+    ``barrier`` is a synchronization method.  It takes exactly one argument, a ``Task``ID or list of taskIDs.  ``barrier`` will block until all the specified Tasks have completed.  In practice, a barrier is often called between the ``Task`` submission section of the code and the result gathering section::
+        
+        In [5]: taskIDs = [ tc.run(``Task``) for ``Task`` in myTasks ]
+        
+        In [6]: tc.get_task_result(taskIDs[-1]) is None
+        Out[6]: ``True``
+        
+        In [7]: tc.barrier(``Task``ID)
+        
+        In [8]: results = [ tc.get_task_result(tid) for tid in taskIDs ]
+        
+ * ``tc.queue_status(verbose=``False``)``
+    ``queue_status`` is a method for querying the state of the ``TaskControler``.  ``queue_status`` returns a dict of the form::
+        
+        {'scheduled': Tasks that have been submitted but yet run
+         'pending'  : Tasks that are currently running
+         'succeeded': Tasks that have completed successfully
+         'failed'   : Tasks that have finished with a failure
+        }
+    
+    if @verbose is not specified (or is ``False``), then the values of the dict are integers - the number of Tasks in each state.  if @verbose is ``True``, then each element in the dict is a list of the taskIDs in that state::
+    
+        In [8]: tc.queue_status()
+        Out[8]: {'scheduled': 4,
+                'pending'  : 2,
+                'succeeded': 5,
+                'failed'   : 1
+                }
+        
+        In [9]: tc.queue_status(verbose=True)
+        Out[9]: {'scheduled': [8,9,10,11],
+                'pending'  : [6,7],
+                'succeeded': [0,1,2,4,5],
+                'failed'   : [3]
+                }
+        
+ * ``tc.abort(taskid)``
+    ``abort`` allows the user to abort Tasks that have already been submitted.  ``abort`` will always return immediately.  If the ``Task`` has completed, ``abort`` will raise an ``IndexError ``Task`` Already Completed``.  An obvious case for ``abort`` would be where the user submits a long-running ``Task`` with a number of retries (see ``Task``_ section for how to specify retries) in an interactive session, but realizes there has been a typo.  The user can then abort the ``Task``, preventing certain failures from cluttering up the queue.  It can also be used for parallel search-type problems, where only one ``Task`` will give the solution, so once the user find the solution, the user would want to abort all remaining Tasks to prevent wasted work.
+ * ``tc.spin()``
+    ``spin`` simply triggers the scheduler in the ``TaskControler``.  Under most normal circumstances, this will do nothing.  The primary known usage case involves the ``Task`` dependency (see `Dependencies`_).  The dependency is a function of an Engine's ``properties``, but changing the ``properties`` via the ``MutliEngineClient`` does not trigger a reschedule event.  The main example case for this requires the following event sequence:
+     * ``engine`` is available, ``Task`` is submitted, but ``engine`` does not have ``Task``'s dependencies.
+     * ``engine`` gets necessary dependencies while no new Tasks are submitted or completed.
+     * now ``engine`` can run ``Task``, but a ``Task`` event is required for the ``TaskControler`` to try scheduling ``Task`` again.
+     
+    ``spin`` is just an empty ping method to ensure that the Controller has scheduled all available Tasks, and should not be needed under most normal circumstances.
+
+That covers the ``TaskClient``, a simple interface to the cluster.  With this, the user can submit jobs (and abort if necessary), request their results, synchronize on arbitrary subsets of jobs.
+
+.. _task: The Task Object
+
+The Task Object
+===============
+
+The ``Task`` is the basic object for describing a job.  It can be used in a very simple manner, where the user just specifies a command string to be executed as the ``Task``.  The usage of this first argument is exactly the same as the ``execute`` method of the ``MultiEngine`` (in fact, ``execute`` is called to run the code)::
+
+    In [1]: t = client.Task("a = str(id)")
+    
+This ``Task`` would run, and store the string representation of the ``id`` element in ``a`` in each worker's namespace, but it is fairly useless because the user does not know anything about the state of the ``worker`` on which it ran at the time of retrieving results.  It is important that each ``Task`` not expect the state of the ``worker`` to persist after the ``Task`` is completed.  
+There are many different situations for using ``Task`` Farming, and the ``Task`` object has many attributes for use in customizing the ``Task`` behavior.  All of a ``Task``'s attributes may be specified in the constructor, through keyword arguments, or after ``Task`` construction through attribute assignment.
+
+Data Attributes
+***************
+It is likely that the user may want to move data around before or after executing the ``Task``.  We provide methods of sending data to initialize the worker's namespace, and specifying what data to bring back as the ``Task``'s results.
+
+ * pull = []
+    The obvious case is as above, where ``t`` would execute and store the result of ``myfunc`` in ``a``, it is likely that the user would want to bring ``a`` back to their namespace.  This is done through the ``pull`` attribute.  ``pull`` can be a string or list of strings, and it specifies the names of variables to be retrieved.  The ``TaskResult`` object retrieved by ``get_task_result`` will have a dictionary of keys and values, and the ``Task``'s ``pull`` attribute determines what goes into it::
+        
+        In [2]: t = client.Task("a = str(id)", pull = "a")
+        
+        In [3]: t = client.Task("a = str(id)", pull = ["a", "id"])
+        
+ * push = {}
+    A user might also want to initialize some data into the namespace before the code part of the ``Task`` is run.  Enter ``push``.  ``push`` is a dictionary of key/value pairs to be loaded from the user's namespace into the worker's immediately before execution::
+
+        In [4]: t = client.Task("a = f(submitted)", push=dict(submitted=time.time()), pull="a")
+
+push and pull result directly in calling an ``engine``'s ``push`` and ``pull`` methods before and after ``Task`` execution respectively, and thus their api is the same.
+
+Namespace Cleaning
+******************
+When a user is running a large number of Tasks, it is likely that the namespace of the worker's could become cluttered.  Some Tasks might be sensitive to clutter, while others might be known to cause namespace pollution.  For these reasons, Tasks have two boolean attributes for cleaning up the namespace.
+
+ * ``clear_after``
+    if clear_after is specified ``True``, the worker on which the ``Task`` was run will be reset (via ``engine.reset``) upon completion of the ``Task``.  This can be useful for both Tasks that produce clutter or Tasks whose intermediate data one might wish to be kept private::
+    
+        In [5]: t = client.Task("a = range(1e10)", pull = "a",clear_after=True)
+        
+    
+ * ``clear_before``
+    as one might guess, clear_before is identical to ``clear_after``, but it takes place before the ``Task`` is run.  This ensures that the ``Task`` runs on a fresh worker::
+
+        In [6]: t = client.Task("a = globals()", pull = "a",clear_before=True)
+
+Of course, a user can both at the same time, ensuring that all workers are clear except when they are currently running a job.  Both of these default to ``False``.
+
+Fault Tolerance
+***************
+It is possible that Tasks might fail, and there are a variety of reasons this could happen.  One might be that the worker it was running on disconnected, and there was nothing wrong with the ``Task`` itself.  With the fault tolerance attributes of the ``Task``, the user can specify how many times to resubmit the ``Task``, and what to do if it never succeeds.
+
+ * ``retries``
+    ``retries`` is an integer, specifying the number of times a ``Task`` is to be retried.  It defaults to zero.  It is often a good idea for this number to be 1 or 2, to protect the ``Task`` from disconnecting engines, but not a large number.  If a ``Task`` is failing 100 times, there is probably something wrong with the ``Task``.  The canonical bad example:
+    
+        In [7]: t = client.Task("os.kill(os.getpid(), 9)", retries=99)
+        
+    This would actually take down 100 workers.
+    
+ * ``recovery_task``
+    ``recovery_task`` is another ``Task`` object, to be run in the event of the original ``Task`` still failing after running out of retries.  Since ``recovery_task`` is another ``Task`` object, it can have its own ``recovery_task``.  The chain of Tasks is limitless, except loops are not allowed (that would be bad!).
+
+Dependencies
+************
+Dependencies are the most powerful part of the ``Task`` farming system, because it allows the user to do some classification of the workers, and guide the ``Task`` distribution without meddling with the controller directly.  It makes use of two objects - the ``Task``'s ``depend`` attribute, and the engine's ``properties``.  See the `MultiEngine`_ reference for how to use engine properties.  The engine properties api exists for extending IPython, allowing conditional execution and new controllers that make decisions based on properties of its engines.  Currently the ``Task`` dependency is the only internal use of the properties api.
+
+.. _MultiEngine: ./parallel_multiengine
+
+The ``depend`` attribute of a ``Task`` must be a function of exactly one argument, the worker's properties dictionary, and it should return ``True`` if the ``Task`` should be allowed to run on the worker and ``False`` if not.  The usage in the controller is fault tolerant, so exceptions raised by ``Task.depend`` will be ignored and functionally equivalent to always returning ``False``.  Tasks`` with invalid ``depend`` functions will never be assigned to a worker::
+
+    In [8]: def dep(properties):
+        ...     return properties["RAM"] > 2**32 # have at least 4GB
+    In [9]: t = client.Task("a = bigfunc()", depend=dep)
+    
+It is important to note that assignment of values to the properties dict is done entirely by the user, either locally (in the engine) using the EngineAPI, or remotely, through the ``MultiEngineClient``'s get/set_properties methods.
+
+
+
+
+
+    

docs/source/development/config_blueprint.txt

@@ -0,0 +1,33
+=========================================
+Notes on the IPython configuration system
+=========================================
+
+This document has some random notes on the configuration system.
+
+To start, an IPython process needs:
+
+* Configuration files
+* Command line options
+* Additional files (FURL files, extra scripts, etc.)
+
+It feeds these things into the core logic of the process, and as output,
+produces:
+
+* Log files
+* Security files
+
+There are a number of things that complicate this:
+
+* A process may need to be started on a different host that doesn't have
+  any of the config files or additional files.  Those files need to be
+  moved over and put in a staging area.  The process then needs to be told
+  about them.
+* The location of the output files should somehow be set by config files or
+  command line options.
+* Our config files are very hierarchical, but command line options are flat,
+  making it difficult to relate command line options to config files.
+* Some processes (like ipcluster and the daemons) have to manage the input and
+  output files for multiple different subprocesses, each possibly on a
+  different host.  Ahhhh!
+* Our configurations are not singletons.  A given user will likely have
+  many different configurations for different clusters.

docs/source/install/install.txt

@@ -0,0 +1,217
+Overview
+========
+
+This document describes the steps required to install IPython.  IPython is organized into a number of subpackages, each of which has its own dependencies.  All of the subpackages come with IPython, so you don't need to download and install them separately.  However, to use a given subpackage, you will need to install all of its dependencies.  
+
+
+Please let us know if you have problems installing IPython or any of its
+dependencies. IPython requires Python version 2.4 or greater.  We have not tested
+IPython with the upcoming 2.6 or 3.0 versions.
+
+.. warning::
+
+	IPython will not work with Python 2.3 or below.
+
+Some of the installation approaches use the :mod:`setuptools` package and its :command:`easy_install` command line program.  In many scenarios, this provides the most simple method of installing IPython and its dependencies.  It is not required though.  More information about :mod:`setuptools` can be found on its website.
+
+More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
+
+Quickstart
+==========
+
+If you have :mod:`setuptools` installed and you are on OS X or Linux (not Windows), the following will download and install IPython *and* the main optional dependencies::
+
+    $ easy_install ipython[kernel,security,test]
+
+This will get Twisted, zope.interface and Foolscap, which are needed for IPython's parallel computing features as well as the nose package, which will enable you to run IPython's test suite.  To run IPython's test suite, use the :command:`iptest` command::
+
+    $ iptest
+
+Read on for more specific details and instructions for Windows.
+
+Installing IPython itself
+=========================
+
+Given a properly built Python, the basic interactive IPython shell will work with no external dependencies.  However, some Python distributions (particularly on Windows and OS X), don't come with a working :mod:`readline` module.  The IPython shell will work without :mod:`readline`, but will lack many features that users depend on, such as tab completion and command line editing.  See below for details of how to make sure you have a working :mod:`readline`.
+
+Installation using easy_install
+-------------------------------
+
+If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`::
+
+	$ easy_install ipython
+
+That's it.
+
+Installation from source
+------------------------
+
+If you don't want to use :command:`easy_install`, or don't have it installed, just grab the latest stable build of IPython from `here <http://ipython.scipy.org/dist/>`_.  Then do the following::
+
+	$ tar -xzf ipython.tar.gz
+	$ cd ipython
+	$ python setup.py install
+
+If you are installing to a location (like ``/usr/local``) that requires higher permissions, you may need to run the last command with :command:`sudo`.
+
+Windows
+-------
+
+There are a few caveats for Windows users.  The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want.  To get an installation with these, there are two choices:
+
+1.  Install using :command:`easy_install`.
+
+2.  Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
+
+3.  Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
+
+Installing the development version
+----------------------------------
+
+It is also possible to install the development version of IPython from our `Bazaar <http://bazaar-vcs.org/>`_ source code
+repository.  To do this you will need to have Bazaar installed on your system.  Then just do::
+
+	$ bzr branch lp:ipython
+	$ cd ipython
+	$ python setup.py install
+
+Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above.
+
+Some users want to be able to follow the development branch as it changes.  If you have :mod:`setuptools` installed, this is easy. Simply replace the last step by::
+
+	$ python setupegg.py develop
+
+This creates links in the right places and installs the command line script to the appropriate places.  Then, if you want to update your IPython at any time, just do::
+
+	$ bzr pull
+
+Basic optional dependencies
+===========================
+
+There are a number of basic optional dependencies that most users will want to get.  These are:
+
+* readline (for command line editing, tab completion, etc.)
+* nose (to run the IPython test suite)
+* pexpect (to use things like irunner)
+
+If you are comfortable installing these things yourself, have at it, otherwise read on for more details.
+
+readline
+--------
+
+In principle, all Python distributions should come with a working :mod:`readline` module.  But, reality is not quite that simple.  There are two common situations where you won't have a working :mod:`readline` module:
+
+* If you are using the built-in Python on Mac OS X.
+
+* If you are running Windows, which doesn't have a :mod:`readline` module.
+
+On OS X, the built-in Python doesn't not have :mod:`readline` because of license issues.  Starting with OS X 10.5 (Leopard), Apple's built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved.  For many users, libedit may be sufficient.
+
+Most users on OS X will want to get the full :mod:`readline` module.  To get a working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
+
+	$ easy_install readline
+
+.. note:
+
+    Other Python distributions on OS X (such as fink, MacPorts and the 
+    official python.org binaries) already have readline installed so 
+    you don't have to do this step.
+
+If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
+
+On Windows, you will need the PyReadline module. PyReadline is a separate,
+Windows only implementation of readline that uses native Windows calls through
+:mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
+installer available `here <http://ipython.scipy.org/dist/>`_. The
+:mod:`ctypes` module, which comes with Python 2.5 and greater, is required by
+PyReadline. It is available for Python 2.4 at
+http://python.net/crew/theller/ctypes.
+
+nose
+----
+
+To run the IPython test suite you will need the :mod:`nose` package.  Nose provides a great way of sniffing out and running all of the IPython tests.  The simplest way of getting nose, is to use :command:`easy_install`::
+
+	$ easy_install nose
+
+Another way of getting this is to do::
+
+    $ easy_install ipython[test]
+
+For more installation options, see the `nose website <http://somethingaboutorange.com/mrl/projects/nose/>`_.  Once you have nose installed, you can run IPython's test suite using the iptest command::
+
+	$ iptest
+
+
+pexpect
+-------
+
+The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's :command:`irunner` script.  On Unix platforms (including OS X), just do::
+
+	$ easy_install pexpect
+
+Windows users are out of luck as pexpect does not run there.
+
+Dependencies for IPython.kernel (parallel computing)
+====================================================
+
+The IPython kernel provides a nice architecture for parallel computing.  The main focus of this architecture is on interactive parallel computing.  These features require a number of additional packages:
+
+* zope.interface (yep, we use interfaces)
+* Twisted (asynchronous networking framework)
+* Foolscap (a nice, secure network protocol)
+* pyOpenSSL (security for network connections)
+
+On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
+
+    $ easy_install ipython[kernel]    # the first three
+    $ easy_install ipython[security]  # pyOpenSSL
+
+zope.interface and Twisted
+--------------------------
+
+Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking related things. On Unix
+style platforms (including OS X), the simplest way of getting the these is to
+use :command:`easy_install`::
+
+	$ easy_install zope.interface
+	$ easy_install Twisted
+
+Of course, you can also download the source tarballs from the `Twisted website <twistedmatrix.org>`_ and the `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python setup.py install`` if you prefer.
+
+Windows is a bit different.  For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website.  This installer includes both zope.interface and Twisted and should just work.
+
+Foolscap
+--------
+
+Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
+
+On all platforms a simple::
+
+    $ easy_install foolscap
+
+should work.  You can also download the source tarballs from the `Foolscap website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install`` if you prefer.
+
+pyOpenSSL
+---------
+
+IPython requires an older version of pyOpenSSL [pyOpenSSL]_ (0.6 rather than the current 0.7).  There are a couple of options for getting this:
+
+1.  Most Linux distributions have packages for pyOpenSSL.
+2.  The built-in Python 2.5 on OS X 10.5 already has it installed.
+3.  There are source tarballs on the pyOpenSSL website.  On Unix-like
+    platforms, these can be built using ``python seutp.py install``.
+4.  There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
+
+Dependencies for IPython.frontend (the IPython GUI)
+===================================================
+
+wxPython
+--------
+
+Starting with IPython 0.9, IPython has a new IPython.frontend package that has a nice wxPython based IPython GUI.  As you would expect, this GUI requires wxPython.  Most Linux distributions have wxPython packages available and the built-in Python on OS X comes with wxPython preinstalled.  For Windows, a binary installer is available on the `wxPython website <http://www.wxpython.org/>`_.
+
+.. [Twisted] Twisted matrix.  http://twistedmatrix.org
+.. [ZopeInterface] http://pypi.python.org/pypi/zope.interface
+.. [Foolscap] Foolscap network protocol.  http://foolscap.lothar.com/trac
+.. [pyOpenSSL] pyOpenSSL.  http://pyopenssl.sourceforge.net
  No newline at end of file

docs/source/parallel/parallel_process.txt

@@ -0,0 +1,251
+.. _parallel_process:
+
+===========================================
+Starting the IPython controller and engines
+===========================================
+
+To use IPython for parallel computing, you need to start one instance of
+the controller and one or more instances of the engine. The controller
+and each engine can run on different machines or on the same machine.
+Because of this, there are many different possibilities.
+
+Broadly speaking, there are two ways of going about starting a controller and engines:
+
+* In an automated manner using the :command:`ipcluster` command.
+* In a more manual way using the :command:`ipcontroller` and 
+  :command:`ipengine` commands.
+
+This document describes both of these methods.  We recommend that new users start with the :command:`ipcluster` command as it simplifies many common usage cases.
+
+General considerations
+======================
+
+Before delving into the details about how you can start a controller and engines using the various methods, we outline some of the general issues that come up when starting the controller and engines.  These things come up no matter which method you use to start your IPython cluster.
+
+Let's say that you want to start the controller on ``host0`` and engines on hosts ``host1``-``hostn``.  The following steps are then required:
+
+1. Start the controller on ``host0`` by running :command:`ipcontroller` on
+   ``host0``.
+2. Move the FURL file (:file:`ipcontroller-engine.furl`) created by the 
+   controller from ``host0`` to hosts ``host1``-``hostn``.
+3. Start the engines on hosts ``host1``-``hostn`` by running 
+   :command:`ipengine`.  This command has to be told where the FURL file 
+   (:file:`ipcontroller-engine.furl`) is located.
+
+At this point, the controller and engines will be connected. By default, the
+FURL files created by the controller are put into the
+:file:`~/.ipython/security` directory. If the engines share a filesystem with
+the controller, step 2 can be skipped as the engines will automatically look
+at that location.
+
+The final step required required to actually use the running controller from a
+client is to move the FURL files :file:`ipcontroller-mec.furl` and
+:file:`ipcontroller-tc.furl` from ``host0`` to the host where the clients will
+be run.  If these file are put into the :file:`~/.ipython/security` directory of the client's host, they will be found automatically.  Otherwise, the full path to them has to be passed to the client's constructor.
+
+Using :command:`ipcluster`
+==========================
+
+The :command:`ipcluster` command provides a simple way of starting a controller and engines in the following situations:
+
+1. When the controller and engines are all run on localhost. This is useful
+   for testing or running on a multicore computer.
+2. When engines are started using the :command:`mpirun` command that comes 
+   with most MPI [MPI]_ implementations
+3. When engines are started using the PBS [PBS]_ batch system.
+
+.. note::
+
+    It is also possible for advanced users to add support to
+    :command:`ipcluster` for starting controllers and engines using other
+    methods (like Sun's Grid Engine for example).
+
+.. note::
+
+    Currently :command:`ipcluster` requires that the
+    :file:`~/.ipython/security` directory live on a shared filesystem that is
+    seen by both the controller and engines. If you don't have a shared file
+    system you will need to use :command:`ipcontroller` and
+    :command:`ipengine` directly.
+
+Underneath the hood, :command:`ipcluster` just uses :command:`ipcontroller`
+and :command:`ipengine` to perform the steps described above.
+
+Using :command:`ipcluster` in local mode
+----------------------------------------
+
+To start one controller and 4 engines on localhost, just do::
+
+    $ ipcluster local -n 4
+
+To see other command line options for the local mode, do::
+
+    $ ipcluster local -h
+
+Using :command:`ipcluster` in mpirun mode
+-----------------------------------------
+
+The mpirun mode is useful if you:
+
+1. Have MPI installed.
+2. Your systems are configured to use the :command:`mpirun` command to start 
+   processes.
+
+If these are satisfied, you can start an IPython cluster using::
+
+    $ ipcluster mpirun -n 4
+
+This does the following:
+
+1. Starts the IPython controller on current host.
+2. Uses :command:`mpirun` to start 4 engines.
+
+On newer MPI implementations (such as OpenMPI), this will work even if you don't make any calls to MPI or call :func:`MPI_Init`.  However, older MPI implementations actually require each process to call :func:`MPI_Init` upon starting.  The easiest way of having this done is to install the mpi4py [mpi4py]_ package and then call ipcluster with the ``--mpi`` option::
+
+    $ ipcluster mpirun -n 4 --mpi=mpi4py
+
+Unfortunately, even this won't work for some MPI implementations.  If you are having problems with this, you will likely have to use a custom Python executable that itself calls :func:`MPI_Init` at the appropriate time.  Fortunately, mpi4py comes with such a custom Python executable that is easy to install and use.  However, this custom Python executable approach will not work with :command:`ipcluster` currently.
+
+Additional command line options for this mode can be found by doing::
+
+    $ ipcluster mpirun -h
+
+More details on using MPI with IPython can be found :ref:`here <parallelmpi>`.
+
+
+Using :command:`ipcluster` in PBS mode
+--------------------------------------
+
+The PBS mode uses the Portable Batch System [PBS]_ to start the engines.  To use this mode, you first need to create a PBS script template that will be used to start the engines.  Here is a sample PBS script template:
+
+.. sourcecode:: bash
+
+    #PBS -N ipython
+    #PBS -j oe
+    #PBS -l walltime=00:10:00
+    #PBS -l nodes=${n/4}:ppn=4
+    #PBS -q parallel
+
+    cd $$PBS_O_WORKDIR
+    export PATH=$$HOME/usr/local/bin
+    export PYTHONPATH=$$HOME/usr/local/lib/python2.4/site-packages
+    /usr/local/bin/mpiexec -n ${n} ipengine --logfile=$$PBS_O_WORKDIR/ipengine
+
+There are a few important points about this template:
+
+1. This template will be rendered at runtime using IPython's :mod:`Itpl` 
+   template engine.
+
+2. Instead of putting in the actual number of engines, use the notation
+   ``${n}`` to indicate the number of engines to be started. You can also uses
+   expressions like ``${n/4}`` in the template to indicate the number of 
+   nodes.
+
+3. Because ``$`` is a special character used by the template engine, you must  
+   escape any ``$`` by using ``$$``.  This is important when referring to 
+   environment variables in the template.
+
+4. Any options to :command:`ipengine` should be given in the batch script 
+   template.
+
+5. Depending on the configuration of you system, you may have to set 
+   environment variables in the script template.
+
+Once you have created such a script, save it with a name like :file:`pbs.template`.  Now you are ready to start your job::
+
+    $ ipcluster pbs -n 128 --pbs-script=pbs.template
+
+Additional command line options for this mode can be found by doing::
+
+    $ ipcluster pbs -h
+
+Using the :command:`ipcontroller` and :command:`ipengine` commands
+==================================================================
+
+It is also possible to use the :command:`ipcontroller` and :command:`ipengine` commands to start your controller and engines.  This approach gives you full control over all aspects of the startup process.
+
+Starting the controller and engine on your local machine
+--------------------------------------------------------
+
+To use :command:`ipcontroller` and :command:`ipengine` to start things on your
+local machine, do the following.
+
+First start the controller::
+
+	$ ipcontroller
+	
+Next, start however many instances of the engine you want using (repeatedly) the command::
+
+	$ ipengine
+
+The engines should start and automatically connect to the controller using the FURL files in :file:`~./ipython/security`. You are now ready to use the controller and engines from IPython.
+
+.. warning:: 
+	
+	The order of the above operations is very important.  You *must*
+ 	start the controller before the engines, since the engines connect 
+	to the controller as they get started.
+
+.. note::
+
+    On some platforms (OS X), to put the controller and engine into the
+    background you may need to give these commands in the form ``(ipcontroller
+    &)`` and ``(ipengine &)`` (with the parentheses) for them to work
+    properly.
+
+Starting the controller and engines on different hosts
+------------------------------------------------------
+
+When the controller and engines are running on different hosts, things are
+slightly more complicated, but the underlying ideas are the same:
+
+1. Start the controller on a host using :command:`ipcontroller`.
+2. Copy :file:`ipcontroller-engine.furl` from :file:`~./ipython/security` on the controller's host to the host where the engines will run.
+3. Use :command:`ipengine` on the engine's hosts to start the engines.
+
+The only thing you have to be careful of is to tell :command:`ipengine` where the :file:`ipcontroller-engine.furl` file is located.  There are two ways you can do this:
+
+* Put :file:`ipcontroller-engine.furl` in the :file:`~./ipython/security`
+  directory on the engine's host, where it will be found automatically.
+* Call :command:`ipengine` with the ``--furl-file=full_path_to_the_file``
+  flag.
+
+The ``--furl-file`` flag works like this::
+
+    $ ipengine --furl-file=/path/to/my/ipcontroller-engine.furl
+
+.. note::
+    
+    If the controller's and engine's hosts all have a shared file system  
+    (:file:`~./ipython/security` is the same on all of them), then things
+    will just work!
+
+Make FURL files persistent
+---------------------------
+
+At fist glance it may seem that that managing the FURL files is a bit annoying.  Going back to the house and key analogy, copying the FURL around each time you start the controller is like having to make a new key every time you want to unlock the door and enter your house.  As with your house, you want to be able to create the key (or FURL file) once, and then simply use it at any point in the future.
+
+This is possible.  The only thing you have to do is decide what ports the controller will listen on for the engines and clients.  This is done as follows::
+
+    $ ipcontroller -r --client-port=10101 --engine-port=10102
+
+Then, just copy the furl files over the first time and you are set.  You can start and stop the controller and engines any many times as you want in the future, just make sure to tell the controller to use the *same* ports.
+
+.. note::
+
+    You may ask the question: what ports does the controller listen on if you
+    don't tell is to use specific ones? The default is to use high random port
+    numbers. We do this for two reasons: i) to increase security through
+    obscurity and ii) to multiple controllers on a given host to start and
+    automatically use different ports.
+
+Log files
+---------
+
+All of the components of IPython have log files associated with them.
+These log files can be extremely useful in debugging problems with
+IPython and can be found in the directory :file:`~/.ipython/log`.  Sending
+the log files to us will often help us to debug any problems.
+
+
+.. [PBS] Portable Batch System.  http://www.openpbs.org/

docs/source/parallel/parallel_security.txt

@@ -0,0 +1,363
+.. _parallelsecurity:
+
+===========================
+Security details of IPython
+===========================
+
+IPython's :mod:`IPython.kernel` package exposes the full power of the Python
+interpreter over a TCP/IP network for the purposes of parallel computing. This
+feature brings up the important question of IPython's security model. This
+document gives details about this model and how it is implemented in IPython's
+architecture.
+
+Processs and network topology
+=============================
+
+To enable parallel computing, IPython has a number of different processes that
+run. These processes are discussed at length in the IPython documentation and
+are summarized here:
+
+* The IPython *engine*.  This process is a full blown Python
+  interpreter in which user code is executed.  Multiple
+  engines are started to make parallel computing possible.
+* The IPython *controller*.  This process manages a set of 
+  engines, maintaining a queue for each and presenting
+  an asynchronous interface to the set of engines.
+* The IPython *client*.  This process is typically an
+  interactive Python process that is used to coordinate the
+  engines to get a parallel computation done.
+
+Collectively, these three processes are called the IPython *kernel*.
+
+These three processes communicate over TCP/IP connections with a well defined
+topology. The IPython controller is the only process that listens on TCP/IP
+sockets. Upon starting, an engine connects to a controller and registers
+itself with the controller. These engine/controller TCP/IP connections persist
+for the lifetime of each engine.
+
+The IPython client also connects to the controller using one or more TCP/IP
+connections. These connections persist for the lifetime of the client only.
+
+A given IPython controller and set of engines typically has a relatively short
+lifetime. Typically this lifetime corresponds to the duration of a single
+parallel simulation performed by a single user. Finally, the controller,
+engines and client processes typically execute with the permissions of that
+same user. More specifically, the controller and engines are *not* executed as
+root or with any other superuser permissions.
+
+Application logic
+=================
+
+When running the IPython kernel to perform a parallel computation, a user
+utilizes the IPython client to send Python commands and data through the
+IPython controller to the IPython engines, where those commands are executed
+and the data processed. The design of IPython ensures that the client is the
+only access point for the capabilities of the engines.  That is, the only way of addressing the engines is through a client.
+
+A user can utilize the client to instruct the IPython engines to execute
+arbitrary Python commands. These Python commands can include calls to the
+system shell, access the filesystem, etc., as required by the user's
+application code. From this perspective, when a user runs an IPython engine on
+a host, that engine has the same capabilities and permissions as the user
+themselves (as if they were logged onto the engine's host with a terminal).
+
+Secure network connections
+==========================
+
+Overview
+--------
+
+All TCP/IP connections between the client and controller as well as the
+engines and controller are fully encrypted and authenticated. This section
+describes the details of the encryption and authentication approached used
+within IPython.
+
+IPython uses the Foolscap network protocol [Foolscap]_ for all communications
+between processes. Thus, the details of IPython's security model are directly
+related to those of Foolscap. Thus, much of the following discussion is
+actually just a discussion of the security that is built in to Foolscap.
+
+Encryption
+----------
+
+For encryption purposes, IPython and Foolscap use the well known Secure Socket
+Layer (SSL) protocol [RFC5246]_. We use the implementation of this protocol
+provided by the OpenSSL project through the pyOpenSSL [pyOpenSSL]_ Python
+bindings to OpenSSL.
+
+Authentication
+--------------
+
+IPython clients and engines must also authenticate themselves with the
+controller. This is handled in a capabilities based security model
+[Capability]_. In this model, the controller creates a strong cryptographic
+key or token that represents each set of capability that the controller
+offers. Any party who has this key and presents it to the controller has full
+access to the corresponding capabilities of the controller. This model is
+analogous to using a physical key to gain access to physical items
+(capabilities) behind a locked door.
+
+For a capabilities based authentication system to prevent unauthorized access,
+two things must be ensured:
+
+* The keys must be cryptographically strong.  Otherwise attackers could gain 
+  access by a simple brute force key guessing attack.
+* The actual keys must be distributed only to authorized parties.
+
+The keys in Foolscap are called Foolscap URL's or FURLs. The following section
+gives details about how these FURLs are created in Foolscap. The IPython
+controller creates a number of FURLs for different purposes:
+
+* One FURL that grants IPython engines access to the controller.  Also
+  implicit in this access is permission to execute code sent by an
+  authenticated IPython client.
+* Two or more FURLs that grant IPython clients access to the controller.
+  Implicit in this access is permission to give the controller's engine code 
+  to execute.
+
+Upon starting, the controller creates these different FURLS and writes them
+files in the user-read-only directory :file:`$HOME/.ipython/security`. Thus, only the
+user who starts the controller has access to the FURLs.
+
+For an IPython client or engine to authenticate with a controller, it must
+present the appropriate FURL to the controller upon connecting. If the
+FURL matches what the controller expects for a given capability, access is
+granted. If not, access is denied. The exchange of FURLs is done after
+encrypted communications channels have been established to prevent attackers
+from capturing them.
+
+.. note::
+
+    The FURL is similar to an unsigned private key in SSH.
+
+Details of the Foolscap handshake
+---------------------------------
+
+In this section we detail the precise security handshake that takes place at
+the beginning of any network connection in IPython. For the purposes of this
+discussion, the SERVER is the IPython controller process and the CLIENT is the
+IPython engine or client process.
+
+Upon starting, all IPython processes do the following:
+
+1. Create a public key x509 certificate (ISO/IEC 9594).
+2. Create a hash of the contents of the certificate using the SHA-1 algorithm.
+   The base-32 encoded version of this hash is saved by the process as its 
+   process id (actually in Foolscap, this is the Tub id, but here refer to
+   it as the process id).
+
+Upon starting, the IPython controller also does the following:
+
+1. Save the x509 certificate to disk in a secure location. The CLIENT
+   certificate is never saved to disk.
+2. Create a FURL for each capability that the controller has.  There are
+   separate capabilities the controller offers for clients and engines.  The
+   FURL is created using:  a) the process id of the SERVER, b) the IP 
+   address and port the SERVER is listening on and c) a 160 bit,    
+   cryptographically secure string that represents the capability (the
+   "capability id").
+3. The FURLs are saved to disk in a secure location on the SERVER's host.
+
+For a CLIENT to be able to connect to the SERVER and access a capability of
+that SERVER, the CLIENT must have knowledge of the FURL for that SERVER's
+capability. This typically requires that the file containing the FURL be
+moved from the SERVER's host to the CLIENT's host. This is done by the end
+user who started the SERVER and wishes to have a CLIENT connect to the SERVER.
+
+When a CLIENT connects to the SERVER, the following handshake protocol takes
+place:
+
+1. The CLIENT tells the SERVER what process (or Tub) id it expects the SERVER
+   to have.
+2. If the SERVER has that process id, it notifies the CLIENT that it will now 
+   enter encrypted mode.  If the SERVER has a different id, the SERVER aborts.
+3. Both CLIENT and SERVER initiate the SSL handshake protocol.
+4. Both CLIENT and SERVER request the certificate of their peer and verify
+   that certificate.  If this succeeds, all further communications are 
+   encrypted.
+5. Both CLIENT and SERVER send a hello block containing connection parameters
+   and their process id.
+6. The CLIENT and SERVER check that their peer's stated process id matches the
+   hash of the x509 certificate the peer presented.  If not, the connection is
+   aborted.
+7. The CLIENT verifies that the SERVER's stated id matches the id of the
+   SERVER the CLIENT is intending to connect to.  If not, the connection is 
+   aborted.
+8. The CLIENT and SERVER elect a master who decides on the final connection
+   parameters.
+
+The public/private key pair associated with each process's x509 certificate
+are completely hidden from this handshake protocol. There are however, used
+internally by OpenSSL as part of the SSL handshake protocol. Each process
+keeps their own private key hidden and sends its peer only the public key
+(embedded in the certificate).
+
+Finally, when the CLIENT requests access to a particular SERVER capability,
+the following happens:
+
+1. The CLIENT asks the SERVER for access to a capability by presenting that 
+   capabilities id.
+2. If the SERVER has a capability with that id, access is granted. If not,
+   access is not granted.
+3. Once access has been gained, the CLIENT can use the capability.
+
+Specific security vulnerabilities
+=================================
+
+There are a number of potential security vulnerabilities present in IPython's
+architecture. In this section we discuss those vulnerabilities and detail how
+the security architecture described above prevents them from being exploited.
+
+Unauthorized clients
+--------------------
+
+The IPython client can instruct the IPython engines to execute arbitrary
+Python code with the permissions of the user who started the engines. If an
+attacker were able to connect their own hostile IPython client to the IPython
+controller, they could instruct the engines to execute code.
+
+This attack is prevented by the capabilities based client authentication
+performed after the encrypted channel has been established. The relevant
+authentication information is encoded into the FURL that clients must
+present to gain access to the IPython controller. By limiting the distribution
+of those FURLs, a user can grant access to only authorized persons.
+
+It is highly unlikely that a client FURL could be guessed by an attacker
+in a brute force guessing attack. A given instance of the IPython controller
+only runs for a relatively short amount of time (on the order of hours). Thus
+an attacker would have only a limited amount of time to test a search space of
+size 2**320. Furthermore, even if a controller were to run for a longer amount
+of time, this search space is quite large (larger for instance than that of
+typical username/password pair).
+
+Unauthorized engines
+--------------------
+
+If an attacker were able to connect a hostile engine to a user's controller,
+the user might unknowingly send sensitive code or data to the hostile engine.
+This attacker's engine would then have full access to that code and data.
+
+This type of attack is prevented in the same way as the unauthorized client
+attack, through the usage of the capabilities based authentication scheme.
+
+Unauthorized controllers
+------------------------
+
+It is also possible that an attacker could try to convince a user's IPython
+client or engine to connect to a hostile IPython controller. That controller
+would then have full access to the code and data sent between the IPython
+client and the IPython engines.
+
+Again, this attack is prevented through the FURLs, which ensure that a
+client or engine connects to the correct controller. It is also important to
+note that the FURLs also encode the IP address and port that the
+controller is listening on, so there is little chance of mistakenly connecting
+to a controller running on a different IP address and port.
+
+When starting an engine or client, a user must specify which FURL to use
+for that connection. Thus, in order to introduce a hostile controller, the
+attacker must convince the user to use the FURLs associated with the
+hostile controller. As long as a user is diligent in only using FURLs from
+trusted sources, this attack is not possible.
+
+Other security measures
+=======================
+
+A number of other measures are taken to further limit the security risks
+involved in running the IPython kernel.
+
+First, by default, the IPython controller listens on random port numbers.
+While this can be overridden by the user, in the default configuration, an
+attacker would have to do a port scan to even find a controller to attack.
+When coupled with the relatively short running time of a typical controller
+(on the order of hours), an attacker would have to work extremely hard and
+extremely *fast* to even find a running controller to attack.
+
+Second, much of the time, especially when run on supercomputers or clusters,
+the controller is running behind a firewall. Thus, for engines or client to
+connect to the controller:
+
+* The different processes have to all be behind the firewall.
+
+or:
+
+* The user has to use SSH port forwarding to tunnel the
+  connections through the firewall.
+   
+In either case, an attacker is presented with addition barriers that prevent
+attacking or even probing the system.
+
+Summary
+=======
+
+IPython's architecture has been carefully designed with security in mind. The
+capabilities based authentication model, in conjunction with the encrypted
+TCP/IP channels, address the core potential vulnerabilities in the system,
+while still enabling user's to use the system in open networks.
+
+Other questions
+===============
+
+About keys
+----------
+
+Can you clarify the roles of the certificate and its keys versus the FURL,
+which is also called a key?
+
+The certificate created by IPython processes is a standard public key x509
+certificate, that is used by the SSL handshake protocol to setup encrypted
+channel between the controller and the IPython engine or client. This public
+and private key associated with this certificate are used only by the SSL
+handshake protocol in setting up this encrypted channel.
+
+The FURL serves a completely different and independent purpose from the
+key pair associated with the certificate. When we refer to a FURL as a
+key, we are using the word "key" in the capabilities based security model
+sense. This has nothing to do with "key" in the public/private key sense used
+in the SSL protocol.
+
+With that said the FURL is used as an cryptographic key, to grant
+IPython engines and clients access to particular capabilities that the
+controller offers.
+
+Self signed certificates
+------------------------
+
+Is the controller creating a self-signed certificate? Is this created for per
+instance/session, one-time-setup or each-time the controller is started?
+
+The Foolscap network protocol, which handles the SSL protocol details, creates
+a self-signed x509 certificate using OpenSSL for each IPython process. The
+lifetime of the certificate is handled differently for the IPython controller
+and the engines/client.
+
+For the IPython engines and client, the certificate is only held in memory for
+the lifetime of its process. It is never written to disk.
+
+For the controller, the certificate can be created anew each time the
+controller starts or it can be created once and reused each time the
+controller starts. If at any point, the certificate is deleted, a new one is
+created the next time the controller starts.
+
+SSL private key
+---------------
+
+How the private key (associated with the certificate) is distributed?
+
+In the usual implementation of the SSL protocol, the private key is never
+distributed. We follow this standard always.
+
+SSL versus Foolscap authentication
+----------------------------------
+
+Many SSL connections only perform one sided authentication (the server to the
+client). How is the client authentication in IPython's system related to SSL
+authentication?
+
+We perform a two way SSL handshake in which both parties request and verify
+the certificate of their peer. This mutual authentication is handled by the
+SSL handshake and is separate and independent from the additional
+authentication steps that the CLIENT and SERVER perform after an encrypted
+channel is established.
+
+.. [RFC5246] <http://tools.ietf.org/html/rfc5246>

docs/sphinxext/inheritance_diagram.py

@@ -0,0 +1,423
+"""
+Defines a docutils directive for inserting inheritance diagrams.
+
+Provide the directive with one or more classes or modules (separated
+by whitespace).  For modules, all of the classes in that module will
+be used.
+
+Example::
+
+   Given the following classes:
+
+   class A: pass
+   class B(A): pass
+   class C(A): pass
+   class D(B, C): pass
+   class E(B): pass
+
+   .. inheritance-diagram: D E
+
+   Produces a graph like the following:
+
+               A
+              / \
+             B   C
+            / \ /
+           E   D
+
+The graph is inserted as a PNG+image map into HTML and a PDF in
+LaTeX.
+"""
+
+import inspect
+import os
+import re
+import subprocess
+try:
+    from hashlib import md5
+except ImportError:
+    from md5 import md5
+
+from docutils.nodes import Body, Element
+from docutils.writers.html4css1 import HTMLTranslator
+from sphinx.latexwriter import LaTeXTranslator
+from docutils.parsers.rst import directives
+from sphinx.roles import xfileref_role
+
+class DotException(Exception):
+    pass
+
+class InheritanceGraph(object):
+    """
+    Given a list of classes, determines the set of classes that
+    they inherit from all the way to the root "object", and then
+    is able to generate a graphviz dot graph from them.
+    """
+    def __init__(self, class_names, show_builtins=False):
+        """
+        *class_names* is a list of child classes to show bases from.
+
+        If *show_builtins* is True, then Python builtins will be shown
+        in the graph.
+        """
+        self.class_names = class_names
+        self.classes = self._import_classes(class_names)
+        self.all_classes = self._all_classes(self.classes)
+        if len(self.all_classes) == 0:
+            raise ValueError("No classes found for inheritance diagram")
+        self.show_builtins = show_builtins
+
+    py_sig_re = re.compile(r'''^([\w.]*\.)?    # class names
+                           (\w+)  \s* $        # optionally arguments
+                           ''', re.VERBOSE)
+
+    def _import_class_or_module(self, name):
+        """
+        Import a class using its fully-qualified *name*.
+        """
+        try:
+            path, base = self.py_sig_re.match(name).groups()
+        except:
+            raise ValueError(
+                "Invalid class or module '%s' specified for inheritance diagram" % name)
+        fullname = (path or '') + base
+        path = (path and path.rstrip('.'))
+        if not path:
+            path = base
+        if not path:
+            raise ValueError(
+                "Invalid class or module '%s' specified for inheritance diagram" % name)
+        try:
+            module = __import__(path, None, None, [])
+        except ImportError:
+            raise ValueError(
+                "Could not import class or module '%s' specified for inheritance diagram" % name)
+
+        try:
+            todoc = module
+            for comp in fullname.split('.')[1:]:
+                todoc = getattr(todoc, comp)
+        except AttributeError:
+            raise ValueError(
+                "Could not find class or module '%s' specified for inheritance diagram" % name)
+
+        # If a class, just return it
+        if inspect.isclass(todoc):
+            return [todoc]
+        elif inspect.ismodule(todoc):
+            classes = []
+            for cls in todoc.__dict__.values():
+                if inspect.isclass(cls) and cls.__module__ == todoc.__name__:
+                    classes.append(cls)
+            return classes
+        raise ValueError(
+            "'%s' does not resolve to a class or module" % name)
+
+    def _import_classes(self, class_names):
+        """
+        Import a list of classes.
+        """
+        classes = []
+        for name in class_names:
+            classes.extend(self._import_class_or_module(name))
+        return classes
+
+    def _all_classes(self, classes):
+        """
+        Return a list of all classes that are ancestors of *classes*.
+        """
+        all_classes = {}
+
+        def recurse(cls):
+            all_classes[cls] = None
+            for c in cls.__bases__:
+                if c not in all_classes:
+                    recurse(c)
+
+        for cls in classes:
+            recurse(cls)
+
+        return all_classes.keys()
+
+    def class_name(self, cls, parts=0):
+        """
+        Given a class object, return a fully-qualified name.  This
+        works for things I've tested in matplotlib so far, but may not
+        be completely general.
+        """
+        module = cls.__module__
+        if module == '__builtin__':
+            fullname = cls.__name__
+        else:
+            fullname = "%s.%s" % (module, cls.__name__)
+        if parts == 0:
+            return fullname
+        name_parts = fullname.split('.')
+        return '.'.join(name_parts[-parts:])
+
+    def get_all_class_names(self):
+        """
+        Get all of the class names involved in the graph.
+        """
+        return [self.class_name(x) for x in self.all_classes]
+
+    # These are the default options for graphviz
+    default_graph_options = {
+        "rankdir": "LR",
+        "size": '"8.0, 12.0"'
+        }
+    default_node_options = {
+        "shape": "box",
+        "fontsize": 10,
+        "height": 0.25,
+        "fontname": "Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",
+        "style": '"setlinewidth(0.5)"'
+        }
+    default_edge_options = {
+        "arrowsize": 0.5,
+        "style": '"setlinewidth(0.5)"'
+        }
+
+    def _format_node_options(self, options):
+        return ','.join(["%s=%s" % x for x in options.items()])
+    def _format_graph_options(self, options):
+        return ''.join(["%s=%s;\n" % x for x in options.items()])
+
+    def generate_dot(self, fd, name, parts=0, urls={},
+                     graph_options={}, node_options={},
+                     edge_options={}):
+        """
+        Generate a graphviz dot graph from the classes that
+        were passed in to __init__.
+
+        *fd* is a Python file-like object to write to.
+
+        *name* is the name of the graph
+
+        *urls* is a dictionary mapping class names to http urls
+
+        *graph_options*, *node_options*, *edge_options* are
+        dictionaries containing key/value pairs to pass on as graphviz
+        properties.
+        """
+        g_options = self.default_graph_options.copy()
+        g_options.update(graph_options)
+        n_options = self.default_node_options.copy()
+        n_options.update(node_options)
+        e_options = self.default_edge_options.copy()
+        e_options.update(edge_options)
+
+        fd.write('digraph %s {\n' % name)
+        fd.write(self._format_graph_options(g_options))
+
+        for cls in self.all_classes:
+            if not self.show_builtins and cls in __builtins__.values():
+                continue
+
+            name = self.class_name(cls, parts)
+
+            # Write the node
+            this_node_options = n_options.copy()
+            url = urls.get(self.class_name(cls))
+            if url is not None:
+                this_node_options['URL'] = '"%s"' % url
+            fd.write('  "%s" [%s];\n' %
+                     (name, self._format_node_options(this_node_options)))
+
+            # Write the edges
+            for base in cls.__bases__:
+                if not self.show_builtins and base in __builtins__.values():
+                    continue
+
+                base_name = self.class_name(base, parts)
+                fd.write('  "%s" -> "%s" [%s];\n' %
+                         (base_name, name,
+                          self._format_node_options(e_options)))
+        fd.write('}\n')
+
+    def run_dot(self, args, name, parts=0, urls={},
+                graph_options={}, node_options={}, edge_options={}):
+        """
+        Run graphviz 'dot' over this graph, returning whatever 'dot'
+        writes to stdout.
+
+        *args* will be passed along as commandline arguments.
+
+        *name* is the name of the graph
+
+        *urls* is a dictionary mapping class names to http urls
+
+        Raises DotException for any of the many os and
+        installation-related errors that may occur.
+        """
+        try:
+            dot = subprocess.Popen(['dot'] + list(args),
+                                   stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                   close_fds=True)
+        except OSError:
+            raise DotException("Could not execute 'dot'.  Are you sure you have 'graphviz' installed?")
+        except ValueError:
+            raise DotException("'dot' called with invalid arguments")
+        except:
+            raise DotException("Unexpected error calling 'dot'")
+
+        self.generate_dot(dot.stdin, name, parts, urls, graph_options,
+                          node_options, edge_options)
+        dot.stdin.close()
+        result = dot.stdout.read()
+        returncode = dot.wait()
+        if returncode != 0:
+            raise DotException("'dot' returned the errorcode %d" % returncode)
+        return result
+
+class inheritance_diagram(Body, Element):
+    """
+    A docutils node to use as a placeholder for the inheritance
+    diagram.
+    """
+    pass
+
+def inheritance_diagram_directive_run(class_names, options, state):
+    """
+    Run when the inheritance_diagram directive is first encountered.
+    """
+    node = inheritance_diagram()
+
+    # Create a graph starting with the list of classes
+    graph = InheritanceGraph(class_names)
+
+    # Create xref nodes for each target of the graph's image map and
+    # add them to the doc tree so that Sphinx can resolve the
+    # references to real URLs later.  These nodes will eventually be
+    # removed from the doctree after we're done with them.
+    for name in graph.get_all_class_names():
+        refnodes, x = xfileref_role(
+            'class', ':class:`%s`' % name, name, 0, state)
+        node.extend(refnodes)
+    # Store the graph object so we can use it to generate the
+    # dot file later
+    node['graph'] = graph
+    # Store the original content for use as a hash
+    node['parts'] = options.get('parts', 0)
+    node['content'] = " ".join(class_names)
+    return [node]
+
+def get_graph_hash(node):
+    return md5(node['content'] + str(node['parts'])).hexdigest()[-10:]
+
+def html_output_graph(self, node):
+    """
+    Output the graph for HTML.  This will insert a PNG with clickable
+    image map.
+    """
+    graph = node['graph']
+    parts = node['parts']
+
+    graph_hash = get_graph_hash(node)
+    name = "inheritance%s" % graph_hash
+    png_path = os.path.join('_static', name + ".png")
+
+    path = '_static'
+    source = self.document.attributes['source']
+    count = source.split('/doc/')[-1].count('/')
+    for i in range(count):
+        if os.path.exists(path): break
+        path = '../'+path
+    path = '../'+path #specifically added for matplotlib
+
+    # Create a mapping from fully-qualified class names to URLs.
+    urls = {}
+    for child in node:
+        if child.get('refuri') is not None:
+            urls[child['reftitle']] = child.get('refuri')
+        elif child.get('refid') is not None:
+            urls[child['reftitle']] = '#' + child.get('refid')
+
+    # These arguments to dot will save a PNG file to disk and write
+    # an HTML image map to stdout.
+    image_map = graph.run_dot(['-Tpng', '-o%s' % png_path, '-Tcmapx'],
+                              name, parts, urls)
+    return ('<img src="%s/%s.png" usemap="#%s" class="inheritance"/>%s' %
+            (path, name, name, image_map))
+
+def latex_output_graph(self, node):
+    """
+    Output the graph for LaTeX.  This will insert a PDF.
+    """
+    graph = node['graph']
+    parts = node['parts']
+
+    graph_hash = get_graph_hash(node)
+    name = "inheritance%s" % graph_hash
+    pdf_path = os.path.join('_static', name + ".pdf")
+
+    graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
+                  name, parts, graph_options={'size': '"6.0,6.0"'})
+    return '\\includegraphics{../../%s}' % pdf_path
+
+def visit_inheritance_diagram(inner_func):
+    """
+    This is just a wrapper around html/latex_output_graph to make it
+    easier to handle errors and insert warnings.
+    """
+    def visitor(self, node):
+        try:
+            content = inner_func(self, node)
+        except DotException, e:
+            # Insert the exception as a warning in the document
+            warning = self.document.reporter.warning(str(e), line=node.line)
+            warning.parent = node
+            node.children = [warning]
+        else:
+            source = self.document.attributes['source']
+            self.body.append(content)
+            node.children = []
+    return visitor
+
+def do_nothing(self, node):
+    pass
+
+options_spec = {
+    'parts': directives.nonnegative_int
+    }
+
+# Deal with the old and new way of registering directives
+try:
+    from docutils.parsers.rst import Directive
+except ImportError:
+    from docutils.parsers.rst.directives import _directives
+    def inheritance_diagram_directive(name, arguments, options, content, lineno,
+                                      content_offset, block_text, state,
+                                      state_machine):
+        return inheritance_diagram_directive_run(arguments, options, state)
+    inheritance_diagram_directive.__doc__ = __doc__
+    inheritance_diagram_directive.arguments = (1, 100, 0)
+    inheritance_diagram_directive.options = options_spec
+    inheritance_diagram_directive.content = 0
+    _directives['inheritance-diagram'] = inheritance_diagram_directive
+else:
+    class inheritance_diagram_directive(Directive):
+        has_content = False
+        required_arguments = 1
+        optional_arguments = 100
+        final_argument_whitespace = False
+        option_spec = options_spec
+
+        def run(self):
+            return inheritance_diagram_directive_run(
+                self.arguments, self.options, self.state)
+    inheritance_diagram_directive.__doc__ = __doc__
+
+    directives.register_directive('inheritance-diagram',
+                                  inheritance_diagram_directive)
+
+def setup(app):
+    app.add_node(inheritance_diagram)
+
+    HTMLTranslator.visit_inheritance_diagram = \
+        visit_inheritance_diagram(html_output_graph)
+    HTMLTranslator.depart_inheritance_diagram = do_nothing
+
+    LaTeXTranslator.visit_inheritance_diagram = \
+        visit_inheritance_diagram(latex_output_graph)
+    LaTeXTranslator.depart_inheritance_diagram = do_nothing

docs/sphinxext/ipython_console_highlighting.py

@@ -0,0 +1,75
+from pygments.lexer import Lexer, do_insertions
+from pygments.lexers.agile import PythonConsoleLexer, PythonLexer, \
+    PythonTracebackLexer
+from pygments.token import Comment, Generic
+from sphinx import highlighting
+import re
+
+line_re = re.compile('.*?\n')
+
+class IPythonConsoleLexer(Lexer):
+    """
+    For IPython console output or doctests, such as:
+
+    Tracebacks are not currently supported.
+
+    .. sourcecode:: ipython
+
+      In [1]: a = 'foo'
+
+      In [2]: a
+      Out[2]: 'foo'
+
+      In [3]: print a
+      foo
+
+      In [4]: 1 / 0
+    """
+    name = 'IPython console session'
+    aliases = ['ipython']
+    mimetypes = ['text/x-ipython-console']
+    input_prompt = re.compile("(In \[[0-9]+\]: )|(   \.\.\.+:)")
+    output_prompt = re.compile("(Out\[[0-9]+\]: )|(   \.\.\.+:)")
+    continue_prompt = re.compile("   \.\.\.+:")
+    tb_start = re.compile("\-+")
+
+    def get_tokens_unprocessed(self, text):
+        pylexer = PythonLexer(**self.options)
+        tblexer = PythonTracebackLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        for match in line_re.finditer(text):
+            line = match.group()
+            input_prompt = self.input_prompt.match(line)
+            continue_prompt = self.continue_prompt.match(line.rstrip())
+            output_prompt = self.output_prompt.match(line)
+            if line.startswith("#"):
+                insertions.append((len(curcode),
+                                   [(0, Comment, line)]))
+            elif input_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, input_prompt.group())]))
+                curcode += line[input_prompt.end():]
+            elif continue_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, continue_prompt.group())]))
+                curcode += line[continue_prompt.end():]
+            elif output_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Output, output_prompt.group())]))
+                curcode += line[output_prompt.end():]
+            else:
+                if curcode:
+                    for item in do_insertions(insertions,
+                                              pylexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                        curcode = ''
+                        insertions = []
+                yield match.start(), Generic.Output, line
+        if curcode:
+            for item in do_insertions(insertions,
+                                      pylexer.get_tokens_unprocessed(curcode)):
+                yield item
+
+highlighting.lexers['ipython'] = IPythonConsoleLexer()

docs/sphinxext/only_directives.py

@@ -0,0 +1,87
+#
+# A pair of directives for inserting content that will only appear in
+# either html or latex.
+#
+
+from docutils.nodes import Body, Element
+from docutils.writers.html4css1 import HTMLTranslator
+from sphinx.latexwriter import LaTeXTranslator
+from docutils.parsers.rst import directives
+
+class html_only(Body, Element):
+    pass
+
+class latex_only(Body, Element):
+    pass
+
+def run(content, node_class, state, content_offset):
+    text = '\n'.join(content)
+    node = node_class(text)
+    state.nested_parse(content, content_offset, node)
+    return [node]
+
+try:
+    from docutils.parsers.rst import Directive
+except ImportError:
+    from docutils.parsers.rst.directives import _directives
+
+    def html_only_directive(name, arguments, options, content, lineno,
+                            content_offset, block_text, state, state_machine):
+        return run(content, html_only, state, content_offset)
+
+    def latex_only_directive(name, arguments, options, content, lineno,
+                             content_offset, block_text, state, state_machine):
+        return run(content, latex_only, state, content_offset)
+
+    for func in (html_only_directive, latex_only_directive):
+        func.content = 1
+        func.options = {}
+        func.arguments = None
+
+    _directives['htmlonly'] = html_only_directive
+    _directives['latexonly'] = latex_only_directive
+else:
+    class OnlyDirective(Directive):
+        has_content = True
+        required_arguments = 0
+        optional_arguments = 0
+        final_argument_whitespace = True
+        option_spec = {}
+
+        def run(self):
+            self.assert_has_content()
+            return run(self.content, self.node_class,
+                       self.state, self.content_offset)
+
+    class HtmlOnlyDirective(OnlyDirective):
+        node_class = html_only
+
+    class LatexOnlyDirective(OnlyDirective):
+        node_class = latex_only
+
+    directives.register_directive('htmlonly', HtmlOnlyDirective)
+    directives.register_directive('latexonly', LatexOnlyDirective)
+
+def setup(app):
+    app.add_node(html_only)
+    app.add_node(latex_only)
+
+    # Add visit/depart methods to HTML-Translator:
+    def visit_perform(self, node):
+        pass
+    def depart_perform(self, node):
+        pass
+    def visit_ignore(self, node):
+        node.children = []
+    def depart_ignore(self, node):
+        node.children = []
+
+    HTMLTranslator.visit_html_only = visit_perform
+    HTMLTranslator.depart_html_only = depart_perform
+    HTMLTranslator.visit_latex_only = visit_ignore
+    HTMLTranslator.depart_latex_only = depart_ignore
+
+    LaTeXTranslator.visit_html_only = visit_ignore
+    LaTeXTranslator.depart_html_only = depart_ignore
+    LaTeXTranslator.visit_latex_only = visit_perform
+    LaTeXTranslator.depart_latex_only = depart_perform

docs/sphinxext/plot_directive.py

@@ -0,0 +1,155
+"""A special directive for including a matplotlib plot.
+
+Given a path to a .py file, it includes the source code inline, then:
+
+- On HTML, will include a .png with a link to a high-res .png.
+
+- On LaTeX, will include a .pdf
+
+This directive supports all of the options of the `image` directive,
+except for `target` (since plot will add its own target).
+
+Additionally, if the :include-source: option is provided, the literal
+source will be included inline, as well as a link to the source.
+"""
+
+import sys, os, glob, shutil
+from docutils.parsers.rst import directives
+
+try:
+    # docutils 0.4
+    from docutils.parsers.rst.directives.images import align
+except ImportError:
+    # docutils 0.5
+    from docutils.parsers.rst.directives.images import Image
+    align = Image.align
+
+
+import matplotlib
+import IPython.Shell
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+
+mplshell = IPython.Shell.MatplotlibShell('mpl')
+
+options = {'alt': directives.unchanged,
+           'height': directives.length_or_unitless,
+           'width': directives.length_or_percentage_or_unitless,
+           'scale': directives.nonnegative_int,
+           'align': align,
+           'class': directives.class_option,
+           'include-source': directives.flag }
+
+template = """
+.. htmlonly::
+
+   [`source code <../%(srcdir)s/%(basename)s.py>`__,
+   `png <../%(srcdir)s/%(basename)s.hires.png>`__,
+   `pdf <../%(srcdir)s/%(basename)s.pdf>`__]
+
+   .. image:: ../%(srcdir)s/%(basename)s.png
+%(options)s
+
+.. latexonly::
+   .. image:: ../%(srcdir)s/%(basename)s.pdf
+%(options)s
+
+"""
+
+def makefig(fullpath, outdir):
+    """
+    run a pyplot script and save the low and high res PNGs and a PDF in _static
+    """
+
+    fullpath = str(fullpath)  # todo, why is unicode breaking this
+    formats = [('png', 100),
+               ('hires.png', 200),
+               ('pdf', 72),
+               ]
+
+    basedir, fname = os.path.split(fullpath)
+    basename, ext = os.path.splitext(fname)
+    all_exists = True
+
+    if basedir != outdir:
+        shutil.copyfile(fullpath, os.path.join(outdir, fname))
+
+    for format, dpi in formats:
+        outname = os.path.join(outdir, '%s.%s' % (basename, format))
+        if not os.path.exists(outname):
+            all_exists = False
+            break
+
+    if all_exists:
+        print '    already have %s'%fullpath
+        return
+
+    print '    building %s'%fullpath
+    plt.close('all')    # we need to clear between runs
+    matplotlib.rcdefaults()
+
+    mplshell.magic_run(fullpath)
+    for format, dpi in formats:
+        outname = os.path.join(outdir, '%s.%s' % (basename, format))
+        if os.path.exists(outname): continue
+        plt.savefig(outname, dpi=dpi)
+
+def run(arguments, options, state_machine, lineno):
+    reference = directives.uri(arguments[0])
+    basedir, fname = os.path.split(reference)
+    basename, ext = os.path.splitext(fname)
+
+    # todo - should we be using the _static dir for the outdir, I am
+    # not sure we want to corrupt that dir with autogenerated files
+    # since it also has permanent files in it which makes it difficult
+    # to clean (save an rm -rf followed by and svn up)
+    srcdir = 'pyplots'
+
+    makefig(os.path.join(srcdir, reference), srcdir)
+
+    # todo: it is not great design to assume the makefile is putting
+    # the figs into the right place, so we may want to do that here instead.
+
+    if options.has_key('include-source'):
+        lines = ['.. literalinclude:: ../pyplots/%(reference)s' % locals()]
+        del options['include-source']
+    else:
+        lines = []
+
+    options = ['      :%s: %s' % (key, val) for key, val in
+               options.items()]
+    options = "\n".join(options)
+
+    lines.extend((template % locals()).split('\n'))
+
+    state_machine.insert_input(
+        lines, state_machine.input_lines.source(0))
+    return []
+
+
+try:
+    from docutils.parsers.rst import Directive
+except ImportError:
+    from docutils.parsers.rst.directives import _directives
+
+    def plot_directive(name, arguments, options, content, lineno,
+                       content_offset, block_text, state, state_machine):
+        return run(arguments, options, state_machine, lineno)
+    plot_directive.__doc__ = __doc__
+    plot_directive.arguments = (1, 0, 1)
+    plot_directive.options = options
+
+    _directives['plot'] = plot_directive
+else:
+    class plot_directive(Directive):
+        required_arguments = 1
+        optional_arguments = 0
+        final_argument_whitespace = True
+        option_spec = options
+        def run(self):
+            return run(self.arguments, self.options,
+                       self.state_machine, self.lineno)
+    plot_directive.__doc__ = __doc__
+
+    directives.register_directive('plot', plot_directive)
+

sandbox/asynparallel.py

@@ -0,0 +1,172
+#!/usr/bin/env python
+"""A parallel tasking tool that uses asynchronous programming. This uses 
+blocking client to get taskid, but returns a Deferred as the result of 
+run(). Users should attach their callbacks on these Deferreds.
+
+Only returning of results is asynchronous. Submitting tasks and getting task
+ids are done synchronously.
+
+Yichun Wei 03/2008
+"""
+
+import inspect
+import itertools
+import numpy as N
+
+from twisted.python import log
+from ipython1.kernel import client
+from ipython1.kernel.client import Task
+
+""" After http://trac.pocoo.org/repos/pocoo/trunk/pocoo/utils/decorators.py
+"""
+class submit_job(object):
+    """ a decorator factory: takes a MultiEngineClient a TaskClient, returns a 
+        decorator, that makes a call to the decorated func as a task in ipython1
+        and submit it to IPython1 controller:
+    """
+    def __init__(self, rc, tc):
+        self.rc = rc
+        self.tc = tc
+
+    def __call__(self, func):
+        return self._decorate(func)
+
+    def _getinfo(self, func):
+        assert inspect.ismethod(func) or inspect.isfunction(func)
+        regargs, varargs, varkwargs, defaults = inspect.getargspec(func)
+        argnames = list(regargs)
+        if varargs:
+            argnames.append(varargs)
+        if varkwargs:
+            argnames.append(varkwargs)
+        counter = itertools.count()
+        fullsign = inspect.formatargspec(
+            regargs, varargs, varkwargs, defaults,
+            formatvalue=lambda value: '=defarg[%i]' % counter.next())[1:-1]
+        shortsign = inspect.formatargspec(
+            regargs, varargs, varkwargs, defaults,
+            formatvalue=lambda value: '')[1:-1]
+        dic = dict(('arg%s' % n, name) for n, name in enumerate(argnames))
+        dic.update(name=func.__name__, argnames=argnames, shortsign=shortsign,
+            fullsign = fullsign, defarg = func.func_defaults or ())
+        return dic
+
+    def _decorate(self, func):
+        """
+        Takes a function and a remote controller and returns a function
+        decorated that is going to submit the job with the controller. 
+        The decorated function is obtained by evaluating a lambda 
+        function with the correct signature.
+
+        the TaskController setupNS doesn't cope with functions, but we
+        can use RemoteController to push functions/modules into engines.
+
+        Changes:
+        200803. In new ipython1, we use push_function for functions.
+        """
+        rc, tc = self.rc, self.tc
+        infodict = self._getinfo(func)
+        if 'rc' in infodict['argnames']:
+            raise NameError, "You cannot use rc as argument names!"
+
+        # we assume the engines' namepace has been prepared.
+        # ns[func.__name__] is already the decorated closure function.
+        # we need to change it back to the original function:
+        ns = {}
+        ns[func.__name__] = func
+
+        # push func and all its environment/prerequesites to engines
+        rc.push_function(ns, block=True) # note it is nonblock by default, not know if it causes problems
+
+        def do_submit_func(*args, **kwds):
+            jobns = {} 
+
+            # Initialize job namespace with args that have default args 
+            # now we support calls that uses default args
+            for n in infodict['fullsign'].split(','):
+                try:
+                    vname, var = n.split('=')
+                    vname, var = vname.strip(), var.strip()
+                except: # no defarg, one of vname, var is None
+                    pass
+                else:
+                    jobns.setdefault(vname, eval(var, infodict))
+
+            # push args and kwds, overwritting default args if needed.
+            nokwds = dict((n,v) for n,v in zip(infodict['argnames'], args)) # truncated
+            jobns.update(nokwds)
+            jobns.update(kwds)
+
+            task = Task('a_very_long_and_rare_name = %(name)s(%(shortsign)s)' % infodict, 
+                pull=['a_very_long_and_rare_name'], push=jobns,)
+            jobid = tc.run(task)
+            # res is a deferred, one can attach callbacks on it
+            res = tc.task_controller.get_task_result(jobid, block=True)
+            res.addCallback(lambda x: x.ns['a_very_long_and_rare_name'])
+            res.addErrback(log.err)
+            return res 
+
+        do_submit_func.rc = rc
+        do_submit_func.tc = tc
+        return do_submit_func
+
+
+def parallelized(rc, tc, initstrlist=[]):
+    """ rc - remote controller
+        tc - taks controller
+        strlist - a list of str that's being executed on engines.
+    """
+    for cmd in initstrlist:
+        rc.execute(cmd, block=True)
+    return submit_job(rc, tc)
+
+
+from twisted.internet import defer
+from numpy import array, nan
+
+def pmap(func, parr, **kwds):
+    """Run func on every element of parr (array), using the elements 
+    as the only one parameter (so you can usually use a dict that 
+    wraps many parameters). -> a result array of Deferreds with the 
+    same shape. func.tc will be used as the taskclient.
+
+    **kwds are passed on to func, not changed.
+    """
+    assert func.tc
+    tc = func.tc
+
+    def run(p, **kwds):
+        if p:
+            return func(p, **kwds)
+        else:
+            return defer.succeed(nan) 
+
+    reslist = [run(p, **kwds).addErrback(log.err) for p in parr.flat]
+    resarr = array(reslist)
+    resarr.shape = parr.shape
+    return resarr
+
+
+if __name__=='__main__':
+
+    rc = client.MultiEngineClient(client.default_address)
+    tc = client.TaskClient(client.default_task_address)
+
+    # if commenting out the decorator you get a local running version 
+    # instantly
+    @parallelized(rc, tc)
+    def f(a, b=1):
+        #from time import sleep 
+        #sleep(1)
+        print "a,b=", a,b
+        return a+b
+
+    def showres(x):
+        print 'ans:',x
+
+    res = f(11,5)
+    res.addCallback(showres)
+
+    # this is not necessary in Twisted 8.0
+    from twisted.internet import reactor
+    reactor.run()

sandbox/minitraits.py

@@ -0,0 +1,119
+import types
+
+class AttributeBase(object):
+    
+    def __get__(self, inst, cls=None):
+        if inst is None:
+            return self
+        try:
+            return inst._attributes[self.name]
+        except KeyError:
+            raise AttributeError("object has no attribute %r" % self.name)
+    
+    def __set__(self, inst, value):
+        actualValue = self.validate(inst, self.name, value)
+        inst._attributes[self.name] = actualValue
+    
+    def validate(self, inst, name, value):
+        raise NotImplementedError("validate must be implemented by a subclass")
+
+class NameFinder(type):
+    
+    def __new__(cls, name, bases, classdict):
+        attributeList = []
+        for k,v in classdict.iteritems():
+            if isinstance(v, AttributeBase):
+                v.name = k
+                attributeList.append(k)
+        classdict['_attributeList'] = attributeList
+        return type.__new__(cls, name, bases, classdict)
+
+class HasAttributes(object):
+    __metaclass__ = NameFinder
+    
+    def __init__(self):
+        self._attributes = {}
+    
+    def getAttributeNames(self):
+        return self._attributeList
+    
+    def getAttributesOfType(self, t, default=None):
+        result = {}
+        for a in self._attributeList:
+            if self.__class__.__dict__[a].__class__ == t:
+                try:
+                    value = getattr(self, a)
+                except AttributeError:
+                    value = None
+                result[a] = value
+        return result
+
+class TypedAttribute(AttributeBase):
+    
+    def validate(self, inst, name, value):
+        if type(value) != self._type:
+            raise TypeError("attribute %s must be of type %s" % (name, self._type))
+        else:
+            return value
+
+# class Option(TypedAttribute):
+#     
+#     _type = types.IntType
+# 
+# class Param(TypedAttribute):
+#     
+#     _type = types.FloatType
+# 
+# class String(TypedAttribute):
+#     
+#     _type = types.StringType
+        
+class TypedSequenceAttribute(AttributeBase):
+    
+    def validate(self, inst, name, value):
+        if type(value) != types.TupleType and type(value) != types.ListType:
+            raise TypeError("attribute %s must be a list or tuple" % (name))
+        else:
+            for item in value:
+                if type(item) != self._subtype:
+                    raise TypeError("attribute %s must be a list or tuple of items with type %s" % (name, self._subtype))
+            return value
+
+# class Instance(AttributeBase):
+#     
+#     def __init__(self, cls):
+#         self.cls = cls
+#     
+#     def validate(self, inst, name, value):
+#         if not isinstance(value, self.cls):
+#             raise TypeError("attribute %s must be an instance of class %s" % (name, self.cls))
+#         else:
+#             return value
+        
+
+# class OptVec(TypedSequenceAttribute):
+#     
+#     _subtype = types.IntType
+# 
+# class PrmVec(TypedSequenceAttribute):
+#     
+#     _subtype = types.FloatType
+# 
+# class StrVec(TypedSequenceAttribute):
+#     
+#     _subtype = types.StringType
+# 
+# 
+# class Bar(HasAttributes):
+#     
+#     a = Option()
+# 
+# class Foo(HasAttributes):
+#     
+#     a = Option()
+#     b = Param()
+#     c = String()
+#     d = OptVec()
+#     e = PrmVec()
+#     f = StrVec()
+#     h = Instance(Bar)
  No newline at end of file

scripts/iptest

@@ -0,0 +1,8
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""IPython Test Suite Runner.
+"""
+
+from IPython.testing import iptest
+
+iptest.main()

tools/compile.py

@@ -0,0 +1,20
+#!/usr/bin/env python
+"""Call the compile script to check that all code we ship compiles correctly.
+"""
+
+import os
+import sys
+
+
+vstr = '.'.join(map(str,sys.version_info[:2]))
+
+stat = os.system('python %s/lib/python%s/compileall.py .' % (sys.prefix,vstr))
+
+print
+if stat:
+    print '*** THERE WAS AN ERROR! ***'
+    print 'See messages above for the actual file that produced it.'
+else:
+    print 'OK'
+
+sys.exit(stat)

IPython/ColorANSI.py

@@ -1,170 +1,182
 # -*- coding: utf-8 -*-
 """Tools for coloring text in ANSI terminals.
 
 $Id: ColorANSI.py 2167 2007-03-21 06:57:50Z fperez $"""
 
 #*****************************************************************************
 #       Copyright (C) 2002-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 IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 __all__ = ['TermColors','InputTermColors','ColorScheme','ColorSchemeTable']
 
 import os
 
 from IPython.ipstruct import Struct
 
 def make_color_table(in_class):
     """Build a set of color attributes in a class.
 
     Helper function for building the *TermColors classes."""
     
     color_templates = (
+        # Dark colors
         ("Black"       , "0;30"),
         ("Red"         , "0;31"),
         ("Green"       , "0;32"),
         ("Brown"       , "0;33"),
         ("Blue"        , "0;34"),
         ("Purple"      , "0;35"),
         ("Cyan"        , "0;36"),
         ("LightGray"   , "0;37"),
+        # Light colors
         ("DarkGray"    , "1;30"),
         ("LightRed"    , "1;31"),
         ("LightGreen"  , "1;32"),
         ("Yellow"      , "1;33"),
         ("LightBlue"   , "1;34"),
         ("LightPurple" , "1;35"),
         ("LightCyan"   , "1;36"),
-        ("White"       , "1;37"),  )
+        ("White"       , "1;37"),  
+        # Blinking colors.  Probably should not be used in anything serious.
+        ("BlinkBlack"  , "5;30"),
+        ("BlinkRed"    , "5;31"),
+        ("BlinkGreen"  , "5;32"),
+        ("BlinkYellow" , "5;33"),
+        ("BlinkBlue"   , "5;34"),
+        ("BlinkPurple" , "5;35"),
+        ("BlinkCyan"   , "5;36"),
+        ("BlinkLightGray", "5;37"),
+        )
 
     for name,value in color_templates:
         setattr(in_class,name,in_class._base % value)
 
 class TermColors:
     """Color escape sequences.
 
     This class defines the escape sequences for all the standard (ANSI?) 
     colors in terminals. Also defines a NoColor escape which is just the null
     string, suitable for defining 'dummy' color schemes in terminals which get
     confused by color escapes.
 
     This class should be used as a mixin for building color schemes."""
     
     NoColor = ''  # for color schemes in color-less terminals.
     Normal = '\033[0m'   # Reset normal coloring
     _base  = '\033[%sm'  # Template for all other colors
 
 # Build the actual color table as a set of class attributes:
 make_color_table(TermColors)
 
 class InputTermColors:
     """Color escape sequences for input prompts.
 
     This class is similar to TermColors, but the escapes are wrapped in \001
     and \002 so that readline can properly know the length of each line and
     can wrap lines accordingly.  Use this class for any colored text which
     needs to be used in input prompts, such as in calls to raw_input().
 
     This class defines the escape sequences for all the standard (ANSI?) 
     colors in terminals. Also defines a NoColor escape which is just the null
     string, suitable for defining 'dummy' color schemes in terminals which get
     confused by color escapes.
 
     This class should be used as a mixin for building color schemes."""
     
     NoColor = ''  # for color schemes in color-less terminals.
 
     if os.name == 'nt' and os.environ.get('TERM','dumb') == 'emacs':
         # (X)emacs on W32 gets confused with \001 and \002 so we remove them
         Normal = '\033[0m'   # Reset normal coloring
         _base  = '\033[%sm'  # Template for all other colors
     else:
         Normal = '\001\033[0m\002'   # Reset normal coloring
         _base  = '\001\033[%sm\002'  # Template for all other colors
 
 # Build the actual color table as a set of class attributes:
 make_color_table(InputTermColors)
 
 class ColorScheme:
     """Generic color scheme class. Just a name and a Struct."""
     def __init__(self,__scheme_name_,colordict=None,**colormap):
         self.name = __scheme_name_
         if colordict is None:
             self.colors = Struct(**colormap)
         else:
             self.colors = Struct(colordict)
 
     def copy(self,name=None):
         """Return a full copy of the object, optionally renaming it."""
         if name is None:
             name = self.name
         return ColorScheme(name,self.colors.__dict__)
         
 class ColorSchemeTable(dict):
     """General class to handle tables of color schemes.
 
     It's basically a dict of color schemes with a couple of shorthand
     attributes and some convenient methods.
     
     active_scheme_name -> obvious
     active_colors -> actual color table of the active scheme"""
 
     def __init__(self,scheme_list=None,default_scheme=''):
         """Create a table of color schemes.
 
         The table can be created empty and manually filled or it can be
         created with a list of valid color schemes AND the specification for
         the default active scheme.
         """
         
         # create object attributes to be set later
         self.active_scheme_name = ''
         self.active_colors = None
         
         if scheme_list:
             if default_scheme == '':
                 raise ValueError,'you must specify the default color scheme'
             for scheme in scheme_list:
                 self.add_scheme(scheme)
             self.set_active_scheme(default_scheme)
 
     def copy(self):
         """Return full copy of object"""
         return ColorSchemeTable(self.values(),self.active_scheme_name)
 
     def add_scheme(self,new_scheme):
         """Add a new color scheme to the table."""
         if not isinstance(new_scheme,ColorScheme):
             raise ValueError,'ColorSchemeTable only accepts ColorScheme instances'
         self[new_scheme.name] = new_scheme
         
     def set_active_scheme(self,scheme,case_sensitive=0):
         """Set the currently active scheme.
 
         Names are by default compared in a case-insensitive way, but this can
         be changed by setting the parameter case_sensitive to true."""
 
         scheme_names = self.keys()
         if case_sensitive:
             valid_schemes = scheme_names
             scheme_test = scheme
         else:
             valid_schemes = [s.lower() for s in scheme_names]
             scheme_test = scheme.lower()
         try:
             scheme_idx = valid_schemes.index(scheme_test)
         except ValueError:
             raise ValueError,'Unrecognized color scheme: ' + scheme + \
                   '\nValid schemes: '+str(scheme_names).replace("'', ",'')
         else:
             active = scheme_names[scheme_idx]
             self.active_scheme_name = active
             self.active_colors = self[active].colors
             # Now allow using '' as an index for the current active scheme
             self[''] = self[active]

IPython/Extensions/ipy_completers.py

@@ -1,394 +1,400
 
 """ Implementations for various useful completers
 
 See Extensions/ipy_stock_completers.py on examples of how to enable a completer,
 but the basic idea is to do:
 
 ip.set_hook('complete_command', svn_completer, str_key = 'svn')
 
 """
 import IPython.ipapi
 import glob,os,shlex,sys
 import inspect
 from time import time
 from zipimport import zipimporter
 ip = IPython.ipapi.get()
 
 try:
     set
 except:
     from sets import Set as set
 
 TIMEOUT_STORAGE = 3 #Time in seconds after which the rootmodules will be stored
 TIMEOUT_GIVEUP = 20 #Time in seconds after which we give up
 
 def quick_completer(cmd, completions):
     """ Easily create a trivial completer for a command.
 
     Takes either a list of completions, or all completions in string
     (that will be split on whitespace)
     
     Example::
     
         [d:\ipython]|1> import ipy_completers                                       
         [d:\ipython]|2> ipy_completers.quick_completer('foo', ['bar','baz'])        
         [d:\ipython]|3> foo b<TAB>
         bar baz                                                                     
         [d:\ipython]|3> foo ba
     """
     if isinstance(completions, basestring):
         
         completions = completions.split()
     def do_complete(self,event):
         return completions
     
     ip.set_hook('complete_command',do_complete, str_key = cmd)
     
 def getRootModules():
     """
     Returns a list containing the names of all the modules available in the
     folders of the pythonpath.
     """
     modules = []
     if ip.db.has_key('rootmodules'):
         return ip.db['rootmodules']
     t = time()
     store = False
     for path in sys.path:
         modules += moduleList(path)        
         if time() - t >= TIMEOUT_STORAGE and not store:
             store = True
             print "\nCaching the list of root modules, please wait!" 
             print "(This will only be done once - type '%rehashx' to " + \
             "reset cache!)"
             print
         if time() - t > TIMEOUT_GIVEUP:
             print "This is taking too long, we give up."
             print
             ip.db['rootmodules'] = []
             return []
     
     modules += sys.builtin_module_names
       
     modules = list(set(modules))
     if '__init__' in modules:
         modules.remove('__init__')
     modules = list(set(modules))
     if store:
         ip.db['rootmodules'] = modules
     return modules
 
 def moduleList(path):
     """
     Return the list containing the names of the modules available in the given
     folder.
     """
 
     if os.path.isdir(path):
         folder_list = os.listdir(path)
     elif path.endswith('.egg'):
         try:
             folder_list = [f for f in zipimporter(path)._files]
         except:
             folder_list = []
     else:
         folder_list = []
     #folder_list = glob.glob(os.path.join(path,'*'))
     folder_list = [p for p in folder_list  \
        if os.path.exists(os.path.join(path, p,'__init__.py'))\
            or p[-3:] in ('.py','.so')\
            or p[-4:] in ('.pyc','.pyo','.pyd')]
 
     folder_list = [os.path.basename(p).split('.')[0] for p in folder_list]
     return folder_list
 
 def moduleCompletion(line):
     """
     Returns a list containing the completion possibilities for an import line.
     The line looks like this :
     'import xml.d'
     'from xml.dom import'
     """
     def tryImport(mod, only_modules=False):
         def isImportable(module, attr):
             if only_modules:
                 return inspect.ismodule(getattr(module, attr))
             else:
                 return not(attr[:2] == '__' and attr[-2:] == '__')
         try:
             m = __import__(mod)
         except:
             return []
         mods = mod.split('.')
         for module in mods[1:]:
             m = getattr(m,module)
         if (not hasattr(m, '__file__')) or (not only_modules) or\
            (hasattr(m, '__file__') and '__init__' in m.__file__):
             completion_list = [attr for attr in dir(m) if isImportable(m, attr)]
         completion_list.extend(getattr(m,'__all__',[]))
         if hasattr(m, '__file__') and '__init__' in m.__file__:
             completion_list.extend(moduleList(os.path.dirname(m.__file__)))
         completion_list = list(set(completion_list))
         if '__init__' in completion_list:
             completion_list.remove('__init__')
         return completion_list
 
     words = line.split(' ')
     if len(words) == 3 and words[0] == 'from':
         return ['import ']
     if len(words) < 3 and (words[0] in ['import','from']) :
         if len(words) == 1:
             return getRootModules()
         mod = words[1].split('.')
         if len(mod) < 2:
             return getRootModules()
         completion_list = tryImport('.'.join(mod[:-1]), True)
         completion_list = ['.'.join(mod[:-1] + [el]) for el in completion_list]
         return completion_list
     if len(words) >= 3 and words[0] == 'from':
         mod = words[1]
         return tryImport(mod)
 
 def vcs_completer(commands, event):
     """ utility to make writing typical version control app completers easier
 
     VCS command line apps typically have the format:
 
     [sudo ]PROGNAME [help] [command] file file...
 
     """
 
 
     cmd_param = event.line.split()
     if event.line.endswith(' '):
         cmd_param.append('')
 
     if cmd_param[0] == 'sudo':
         cmd_param = cmd_param[1:]
 
     if len(cmd_param) == 2 or 'help' in cmd_param:
         return commands.split()
 
     return ip.IP.Completer.file_matches(event.symbol)
 
 
 pkg_cache = None
 
 def module_completer(self,event):
     """ Give completions after user has typed 'import ...' or 'from ...'"""
 
     # This works in all versions of python.  While 2.5 has
     # pkgutil.walk_packages(), that particular routine is fairly dangerous,
     # since it imports *EVERYTHING* on sys.path.  That is: a) very slow b) full
     # of possibly problematic side effects.
     # This search the folders in the sys.path for available modules.
 
     return moduleCompletion(event.line)
 
 
 svn_commands = """\
 add blame praise annotate ann cat checkout co cleanup commit ci copy
 cp delete del remove rm diff di export help ? h import info list ls
 lock log merge mkdir move mv rename ren propdel pdel pd propedit pedit
 pe propget pget pg proplist plist pl propset pset ps resolved revert
 status stat st switch sw unlock update
 """
 
 def svn_completer(self,event):
     return vcs_completer(svn_commands, event)
 
 
 hg_commands = """
 add addremove annotate archive backout branch branches bundle cat
 clone commit copy diff export grep heads help identify import incoming
 init locate log manifest merge outgoing parents paths pull push
 qapplied qclone qcommit qdelete qdiff qfold qguard qheader qimport
 qinit qnew qnext qpop qprev qpush qrefresh qrename qrestore qsave
 qselect qseries qtop qunapplied recover remove rename revert rollback
 root serve showconfig status strip tag tags tip unbundle update verify
 version
 """
 
 def hg_completer(self,event):
     """ Completer for mercurial commands """
 
     return vcs_completer(hg_commands, event)
 
 
 
 __bzr_commands = None
 
 def bzr_commands():
     global __bzr_commands
     if __bzr_commands is not None:
         return __bzr_commands
     out = os.popen('bzr help commands')
     __bzr_commands = [l.split()[0] for l in out]
     return __bzr_commands                
 
 def bzr_completer(self,event):
     """ Completer for bazaar commands """
     cmd_param = event.line.split()
     if event.line.endswith(' '):
         cmd_param.append('')
 
     if len(cmd_param) > 2:
         cmd = cmd_param[1]
         param = cmd_param[-1]
         output_file = (param == '--output=')
         if cmd == 'help':
             return bzr_commands()
         elif cmd in ['bundle-revisions','conflicts',
                      'deleted','nick','register-branch',
                      'serve','unbind','upgrade','version',
                      'whoami'] and not output_file:
             return []
         else:
             # the rest are probably file names
             return ip.IP.Completer.file_matches(event.symbol)
 
     return bzr_commands()
 
 
 def shlex_split(x):
     """Helper function to split lines into segments."""
     #shlex.split raise exception if syntax error in sh syntax
     #for example if no closing " is found. This function keeps dropping
     #the last character of the line until shlex.split does not raise
     #exception. Adds end of the line to the result of shlex.split
     #example: %run "c:/python  -> ['%run','"c:/python']
     endofline=[]
     while x!="":
         try:
             comps=shlex.split(x)
             if len(endofline)>=1:
                 comps.append("".join(endofline))
             return comps
         except ValueError:
             endofline=[x[-1:]]+endofline
             x=x[:-1]
     return ["".join(endofline)]
 
 def runlistpy(self, event):
     comps = shlex_split(event.line)
     relpath = (len(comps) > 1 and comps[-1] or '').strip("'\"")
 
     #print "\nev=",event  # dbg
     #print "rp=",relpath  # dbg
     #print 'comps=',comps  # dbg
 
     lglob = glob.glob
     isdir = os.path.isdir
     if relpath.startswith('~'):
         relpath = os.path.expanduser(relpath)
     dirs = [f.replace('\\','/') + "/" for f in lglob(relpath+'*')
             if isdir(f)]
 
     # Find if the user has already typed the first filename, after which we
     # should complete on all files, since after the first one other files may
     # be arguments to the input script.
     #filter(
     if filter(lambda f: f.endswith('.py') or f.endswith('.ipy') or
               f.endswith('.pyw'),comps):
         pys =  [f.replace('\\','/') for f in lglob('*')]
     else:
         pys =  [f.replace('\\','/')
                 for f in lglob(relpath+'*.py') + lglob(relpath+'*.ipy') +
                 lglob(relpath + '*.pyw')]
     return dirs + pys
 
 
 greedy_cd_completer = False
 
 def cd_completer(self, event):
     relpath = event.symbol
     #print event # dbg
     if '-b' in event.line:
         # return only bookmark completions
         bkms = self.db.get('bookmarks',{})
         return bkms.keys()
 
     
     if event.symbol == '-':
         width_dh = str(len(str(len(ip.user_ns['_dh']) + 1)))
         # jump in directory history by number
         fmt = '-%0' + width_dh +'d [%s]'
         ents = [ fmt % (i,s) for i,s in enumerate(ip.user_ns['_dh'])]
         if len(ents) > 1:
             return ents
         return []
 
     if event.symbol.startswith('--'):
         return ["--" + os.path.basename(d) for d in ip.user_ns['_dh']]
     
     if relpath.startswith('~'):
         relpath = os.path.expanduser(relpath).replace('\\','/')
     found = []
     for d in [f.replace('\\','/') + '/' for f in glob.glob(relpath+'*')
               if os.path.isdir(f)]:
         if ' ' in d:
             # we don't want to deal with any of that, complex code
             # for this is elsewhere
             raise IPython.ipapi.TryNext
         found.append( d )
 
     if not found:
         if os.path.isdir(relpath):
             return [relpath]
+        # if no completions so far, try bookmarks
+        bks = self.db.get('bookmarks',{}).keys()
+        bkmatches = [s for s in bks if s.startswith(event.symbol)]
+        if bkmatches:
+            return bkmatches
+        
         raise IPython.ipapi.TryNext
 
 
     def single_dir_expand(matches):
         "Recursively expand match lists containing a single dir."
         
         if len(matches) == 1 and os.path.isdir(matches[0]):
             # Takes care of links to directories also.  Use '/'
             # explicitly, even under Windows, so that name completions
             # don't end up escaped.
             d = matches[0]
             if d[-1] in ['/','\\']:
                 d = d[:-1]
 
             subdirs = [p for p in os.listdir(d) if os.path.isdir( d + '/' + p) and not p.startswith('.')]
             if subdirs:
                 matches = [ (d + '/' + p) for p in subdirs ]
                 return single_dir_expand(matches)
             else:
                 return matches
         else:
             return matches
 
     if greedy_cd_completer:
         return single_dir_expand(found)
     else:
         return found
 
 def apt_get_packages(prefix):
     out = os.popen('apt-cache pkgnames')
     for p in out:
         if p.startswith(prefix):
             yield p.rstrip()
     
     
 apt_commands = """\
 update upgrade install remove purge source build-dep dist-upgrade
 dselect-upgrade clean autoclean check"""
 
 def apt_completer(self, event):
     """ Completer for apt-get (uses apt-cache internally)
 
     """
 
 
     cmd_param = event.line.split()
     if event.line.endswith(' '):
         cmd_param.append('')
 
     if cmd_param[0] == 'sudo':
         cmd_param = cmd_param[1:]
 
     if len(cmd_param) == 2 or 'help' in cmd_param:
         return apt_commands.split()
 
     return list(apt_get_packages(event.symbol))
 

IPython/Extensions/ipy_editors.py

@@ -1,84 +1,88
 """ 'editor' hooks for common editors that work well with ipython
 
 They should honor the line number argument, at least.
 
 Contributions are *very* welcome.
 """
 
 import IPython.ipapi
 ip = IPython.ipapi.get()
 
 from IPython.Itpl import itplns
 import os
 
 def install_editor(run_template, wait = False):
     """ Gets a template in format "myeditor bah bah $file bah bah $line"
     
     $file will be replaced by file name, $line by line number (or 0).
     Installs the editor that is called by IPython, instead of the default
     notepad or vi.
     
     If wait is true, wait until the user presses enter before returning,
     to facilitate non-blocking editors that exit immediately after
     the call.
     """
     
     def call_editor(self, file, line=0):
         if line is None:
             line = 0
         cmd = itplns(run_template, locals())
         print ">",cmd
-        os.system(cmd)
+        if os.system(cmd) != 0:
+            raise IPython.ipapi.TryNext()
         if wait:
             raw_input("Press Enter when done editing:")
 
     ip.set_hook('editor',call_editor)
 
 
 # in these, exe is always the path/name of the executable. Useful
 # if you don't have the editor directory in your path
 
 def komodo(exe = 'komodo'):
     """ Activestate Komodo [Edit] """
     install_editor(exe + ' -l $line "$file"', wait = True)
 
 def scite(exe = "scite"):
     """ SciTE or Sc1 """
     install_editor(exe + ' "$file" -goto:$line')
 
 def notepadplusplus(exe = 'notepad++'):
     """ Notepad++ http://notepad-plus.sourceforge.net """
     install_editor(exe + ' -n$line "$file"')
     
 def jed(exe = 'jed'):
     """ JED, the lightweight emacsish editor """
     install_editor(exe + ' +$line "$file"')
 
 def idle(exe = None):
     """ Idle, the editor bundled with python
     
     Should be pretty smart about finding the executable.
     """
     if exe is None:
         import idlelib
         p = os.path.dirname(idlelib.__file__)
         exe = p + '/idle.py'
     install_editor(exe + ' "$file"')
-        
+
+def mate(exe = 'mate'):
+    """ TextMate, the missing editor"""
+    install_editor(exe + ' -w -l $line "$file"')
 
 # these are untested, report any problems
 
 def emacs(exe = 'emacs'):
     install_editor(exe + ' +$line "$file"')
 
 def gnuclient(exe= 'gnuclient'):
     install_editor(exe + ' -nw +$line "$file"')
 
 def crimson_editor(exe = 'cedt.exe'):
     install_editor(exe + ' /L:$line "$file"')
     
 def kate(exe = 'kate'):
     install_editor(exe + ' -u -l $line "$file"')
     
    
     
  No newline at end of file

IPython/Extensions/ipy_profile_sh.py

@@ -1,258 +1,270
 """Shell mode for IPython.
 
 Start ipython in shell mode by invoking "ipython -p sh"
 
 (the old version, "ipython -p pysh" still works but this is the more "modern" 
 shell mode and is recommended for users who don't care about pysh-mode
 compatibility)
 """
 
 from IPython import ipapi
-import os,textwrap
+import os,re,textwrap
 
 # The import below effectively obsoletes your old-style ipythonrc[.ini],
 # so consider yourself warned!
 
 import ipy_defaults
 
 def main():    
     ip = ipapi.get()
     o = ip.options
     # autocall to "full" mode (smart mode is default, I like full mode)
     
     o.autocall = 2
     
     # Jason Orendorff's path class is handy to have in user namespace
     # if you are doing shell-like stuff
     try:
         ip.ex("from IPython.external.path import path" )
     except ImportError:
         pass
     
     # beefed up %env is handy in shell mode
     import envpersist
     
     # To see where mycmd resides (in path/aliases), do %which mycmd 
     import ipy_which
     
     # tab completers for hg, svn, ...
     import ipy_app_completers
     
     # To make executables foo and bar in mybin usable without PATH change, do:
     # %rehashdir c:/mybin
     # %store foo
     # %store bar
     import ipy_rehashdir
 
     # does not work without subprocess module!
     #import ipy_signals
     
     ip.ex('import os')
     ip.ex("def up(): os.chdir('..')")
     ip.user_ns['LA'] = LastArgFinder() 
-    # Nice prompt
     
-    o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#> '
+    # You can assign to _prompt_title variable 
+    # to provide some extra information for prompt
+    # (e.g. the current mode, host/username...)
+
+    ip.user_ns['_prompt_title'] = ''
+    
+    # Nice prompt
+    o.prompt_in1= r'\C_Green${_prompt_title}\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#> '
     o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green> '
     o.prompt_out= '<\#> '
     
     from IPython import Release
 
     import sys
     # Non-chatty banner
     o.banner = "IPython %s   [on Py %s]\n" % (Release.version,sys.version.split(None,1)[0])
     
     
     ip.IP.default_option('cd','-q')
     ip.IP.default_option('macro', '-r')
     # If you only rarely want to execute the things you %edit...  
     #ip.IP.default_option('edit','-x')
     
 
     o.prompts_pad_left="1"
     # Remove all blank lines in between prompts, like a normal shell.
     o.separate_in="0"
     o.separate_out="0"
     o.separate_out2="0"
     
     # now alias all syscommands
     
     db = ip.db
     
     syscmds = db.get("syscmdlist",[] )
     if not syscmds:
         print textwrap.dedent("""
         System command list not initialized, probably the first run...
         running %rehashx to refresh the command list. Run %rehashx
         again to refresh command list (after installing new software etc.)
         """)
         ip.magic('rehashx')
         syscmds = db.get("syscmdlist")
     
     # lowcase aliases on win32 only
     if os.name == 'posix':
         mapper = lambda s:s
     else:
         def mapper(s): return s.lower()
         
     for cmd in syscmds:
         # print "sys",cmd #dbg
         noext, ext = os.path.splitext(cmd)
-        key = mapper(noext)
+        if ext.lower() == '.exe':
+            cmd = noext
+        
+        key = mapper(cmd)
         if key not in ip.IP.alias_table:
-            ip.defalias(key, cmd)
+            # Dots will be removed from alias names, since ipython
+            # assumes names with dots to be python code
+            
+            ip.defalias(key.replace('.',''), cmd)
 
     # mglob combines 'find', recursion, exclusion... '%mglob?' to learn more
     ip.load("IPython.external.mglob")    
 
     # win32 is crippled w/o cygwin, try to help it a little bit
     if sys.platform == 'win32':
         if 'cygwin' in os.environ['PATH'].lower():          
             # use the colors of cygwin ls (recommended)
             ip.defalias('d', 'ls -F --color=auto')
         else:
             # get icp, imv, imkdir, igrep, irm,...
             ip.load('ipy_fsops')
             
             # and the next best thing to real 'ls -F'
             ip.defalias('d','dir /w /og /on')
     
-    ip.set_hook('input_prefilter', dotslash_prefilter_f)
+    ip.set_hook('input_prefilter', slash_prefilter_f)
     extend_shell_behavior(ip)
 
 class LastArgFinder:
     """ Allow $LA to work as "last argument of previous command", like $! in bash
     
     To call this in normal IPython code, do LA()
     """
     def __call__(self, hist_idx = None):
         ip = ipapi.get()
         if hist_idx is None:
             return str(self)
         return ip.IP.input_hist_raw[hist_idx].strip().split()[-1]
     def __str__(self):
         ip = ipapi.get()        
         for cmd in reversed(ip.IP.input_hist_raw):
             parts = cmd.strip().split()
             if len(parts) < 2 or parts[-1] in ['$LA', 'LA()']:
                 continue
             return parts[-1]
         return ""
 
-def dotslash_prefilter_f(self,line):
-    """ ./foo now runs foo as system command 
+def slash_prefilter_f(self,line):
+    """ ./foo, ~/foo and /bin/foo now run foo as system command
     
-    Removes the need for doing !./foo
+    Removes the need for doing !./foo, !~/foo or !/bin/foo
     """
     import IPython.genutils
-    if line.startswith("./"):
+    if re.match('(?:[.~]|/[a-zA-Z_0-9]+)/', line):
         return "_ip.system(" + IPython.genutils.make_quoted_expr(line)+")"
     raise ipapi.TryNext
 
 # XXX You do not need to understand the next function!
 # This should probably be moved out of profile
 
 def extend_shell_behavior(ip):
 
     # Instead of making signature a global variable tie it to IPSHELL.
     # In future if it is required to distinguish between different
     # shells we can assign a signature per shell basis
     ip.IP.__sig__ = 0xa005
     # mark the IPSHELL with this signature
     ip.IP.user_ns['__builtins__'].__dict__['__sig__'] = ip.IP.__sig__
 
     from IPython.Itpl import ItplNS
     from IPython.genutils import shell
     # utility to expand user variables via Itpl
     # xxx do something sensible with depth?
     ip.IP.var_expand = lambda cmd, lvars=None, depth=2: \
         str(ItplNS(cmd, ip.IP.user_ns, get_locals()))
 
     def get_locals():
         """ Substituting a variable through Itpl deep inside the IPSHELL stack
             requires the knowledge of all the variables in scope upto the last
             IPSHELL frame. This routine simply merges all the local variables
             on the IPSHELL stack without worrying about their scope rules
         """
         import sys
         # note lambda expression constitues a function call
         # hence fno should be incremented by one
         getsig = lambda fno: sys._getframe(fno+1).f_globals \
                              ['__builtins__'].__dict__['__sig__']
         getlvars = lambda fno: sys._getframe(fno+1).f_locals
         # trackback until we enter the IPSHELL
         frame_no = 1
         sig = ip.IP.__sig__
         fsig = ~sig
         while fsig != sig :
             try:
                 fsig = getsig(frame_no)
             except (AttributeError, KeyError):
                 frame_no += 1
             except ValueError:
                 # stack is depleted
                 # call did not originate from IPSHELL
                 return {}
         first_frame = frame_no
         # walk further back until we exit from IPSHELL or deplete stack
         try:
             while(sig == getsig(frame_no+1)):
                 frame_no += 1
         except (AttributeError, KeyError, ValueError):
             pass
         # merge the locals from top down hence overriding
         # any re-definitions of variables, functions etc.
         lvars = {}
         for fno in range(frame_no, first_frame-1, -1):
             lvars.update(getlvars(fno))
         #print '\n'*5, first_frame, frame_no, '\n', lvars, '\n'*5 #dbg
         return lvars
 
     def _runlines(lines):
         """Run a string of one or more lines of source.
 
         This method is capable of running a string containing multiple source
         lines, as if they had been entered at the IPython prompt.  Since it
         exposes IPython's processing machinery, the given strings can contain
         magic calls (%magic), special shell access (!cmd), etc."""
 
         # We must start with a clean buffer, in case this is run from an
         # interactive IPython session (via a magic, for example).
         ip.IP.resetbuffer()
         lines = lines.split('\n')
         more = 0
         command = ''
         for line in lines:
             # skip blank lines so we don't mess up the prompt counter, but do
             # NOT skip even a blank line if we are in a code block (more is
             # true)
             # if command is not empty trim the line
             if command != '' :
                 line = line.strip()
             # add the broken line to the command
             if line and line[-1] == '\\' :
                 command += line[0:-1] + ' '
                 more = True
                 continue
             else :
                 # add the last (current) line to the command
                 command += line
                 if command or more:
                     # push to raw history, so hist line numbers stay in sync
                     ip.IP.input_hist_raw.append("# " + command + "\n")
                     
                     more = ip.IP.push(ip.IP.prefilter(command,more))
                     command = ''
                     # IPython's runsource returns None if there was an error
                     # compiling the code.  This allows us to stop processing right
                     # away, so the user gets the error message at the right place.
                     if more is None:
                         break
         # final newline in case the input didn't have it, so that the code
         # actually does get executed
         if more:
             ip.IP.push('\n')
 
     ip.IP.runlines = _runlines
 
 main()

IPython/Magic.py

@@ -1,3377 +1,3405
 # -*- coding: utf-8 -*-
 """Magic functions for InteractiveShell.
 
 $Id: Magic.py 2996 2008-01-30 06:31:39Z fperez $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
 #       Copyright (C) 2001-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.
 #*****************************************************************************
 
 #****************************************************************************
 # Modules and globals
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % \
               ( Release.authors['Janko'] + Release.authors['Fernando'] )
 __license__ = Release.license
 
 # Python standard modules
 import __builtin__
 import bdb
 import inspect
 import os
 import pdb
 import pydoc
 import sys
 import re
 import tempfile
 import time
 import cPickle as pickle
 import textwrap
 from cStringIO import StringIO
 from getopt import getopt,GetoptError
 from pprint import pprint, pformat
 from sets import Set
 
 # cProfile was added in Python2.5
 try:
     import cProfile as profile
     import pstats
 except ImportError:
     # profile isn't bundled by default in Debian for license reasons
     try:
         import profile,pstats
     except ImportError:
         profile = pstats = None
 
 # Homebrewed
 import IPython
 from IPython import Debugger, OInspect, wildcard
 from IPython.FakeModule import FakeModule
 from IPython.Itpl import Itpl, itpl, printpl,itplns
 from IPython.PyColorize import Parser
 from IPython.ipstruct import Struct
 from IPython.macro import Macro
 from IPython.genutils import *
 from IPython import platutils
 import IPython.generics
 import IPython.ipapi
 from IPython.ipapi import UsageError
 from IPython.testing import decorators as testdec
 
 #***************************************************************************
 # Utility functions
 def on_off(tag):
     """Return an ON/OFF string for a 1/0 input. Simple utility function."""
     return ['OFF','ON'][tag]
 
 class Bunch: pass
 
 def compress_dhist(dh):
     head, tail = dh[:-10], dh[-10:]
 
     newhead = []
     done = Set()
     for h in head:
         if h in done:
             continue
         newhead.append(h)
         done.add(h)
 
     return newhead + tail        
         
 
 #***************************************************************************
 # Main class implementing Magic functionality
 class Magic:
     """Magic functions for InteractiveShell.
 
     Shell functions which can be reached as %function_name. All magic
     functions should accept a string, which they can parse for their own
     needs. This can make some functions easier to type, eg `%cd ../`
     vs. `%cd("../")`
 
     ALL definitions MUST begin with the prefix magic_. The user won't need it
     at the command line, but it is is needed in the definition. """
 
     # class globals
     auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
                    'Automagic is ON, % prefix NOT needed for magic functions.']
 
     #......................................................................
     # some utility functions
 
     def __init__(self,shell):
         
         self.options_table = {}
         if profile is None:
             self.magic_prun = self.profile_missing_notice
         self.shell = shell
 
         # namespace for holding state we may need
         self._magic_state = Bunch()
 
     def profile_missing_notice(self, *args, **kwargs):
         error("""\
 The profile module could not be found. It has been removed from the standard
 python packages because of its non-free license. To use profiling, install the
 python-profiler package from non-free.""")
 
     def default_option(self,fn,optstr):
         """Make an entry in the options_table for fn, with value optstr"""
 
         if fn not in self.lsmagic():
             error("%s is not a magic function" % fn)
         self.options_table[fn] = optstr
 
     def lsmagic(self):
         """Return a list of currently available magic functions.
 
         Gives a list of the bare names after mangling (['ls','cd', ...], not
         ['magic_ls','magic_cd',...]"""
 
         # FIXME. This needs a cleanup, in the way the magics list is built.
         
         # magics in class definition
         class_magic = lambda fn: fn.startswith('magic_') and \
                       callable(Magic.__dict__[fn])
         # in instance namespace (run-time user additions)
         inst_magic =  lambda fn: fn.startswith('magic_') and \
                      callable(self.__dict__[fn])
         # and bound magics by user (so they can access self):
         inst_bound_magic =  lambda fn: fn.startswith('magic_') and \
                            callable(self.__class__.__dict__[fn])
         magics = filter(class_magic,Magic.__dict__.keys()) + \
                  filter(inst_magic,self.__dict__.keys()) + \
                  filter(inst_bound_magic,self.__class__.__dict__.keys())
         out = []
         for fn in Set(magics):
             out.append(fn.replace('magic_','',1))
         out.sort()
         return out
     
     def extract_input_slices(self,slices,raw=False):
         """Return as a string a set of input history slices.
 
         Inputs:
 
           - slices: the set of slices is given as a list of strings (like
           ['1','4:8','9'], since this function is for use by magic functions
           which get their arguments as strings.
 
         Optional inputs:
 
           - raw(False): by default, the processed input is used.  If this is
           true, the raw input history is used instead.
 
         Note that slices can be called with two notations:
 
         N:M -> standard python form, means including items N...(M-1).
 
         N-M -> include items N..M (closed endpoint)."""
 
         if raw:
             hist = self.shell.input_hist_raw
         else:
             hist = self.shell.input_hist
 
         cmds = []
         for chunk in slices:
             if ':' in chunk:
                 ini,fin = map(int,chunk.split(':'))
             elif '-' in chunk:
                 ini,fin = map(int,chunk.split('-'))
                 fin += 1
             else:
                 ini = int(chunk)
                 fin = ini+1
             cmds.append(hist[ini:fin])
         return cmds
         
     def _ofind(self, oname, namespaces=None):
         """Find an object in the available namespaces.
 
         self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
 
         Has special code to detect magic functions.
         """
         
         oname = oname.strip()
 
         alias_ns = None
         if namespaces is None:
             # Namespaces to search in:
             # Put them in a list. The order is important so that we
             # find things in the same order that Python finds them.
             namespaces = [ ('Interactive', self.shell.user_ns),
                            ('IPython internal', self.shell.internal_ns),
                            ('Python builtin', __builtin__.__dict__),
                            ('Alias', self.shell.alias_table),
                            ]
             alias_ns = self.shell.alias_table
 
         # initialize results to 'null'
         found = 0; obj = None;  ospace = None;  ds = None;
         ismagic = 0; isalias = 0; parent = None
 
         # Look for the given name by splitting it in parts.  If the head is
         # found, then we look for all the remaining parts as members, and only
         # declare success if we can find them all.
         oname_parts = oname.split('.')
         oname_head, oname_rest = oname_parts[0],oname_parts[1:]
         for nsname,ns in namespaces:
             try:
                 obj = ns[oname_head]
             except KeyError:
                 continue
             else:
                 #print 'oname_rest:', oname_rest  # dbg
                 for part in oname_rest:
                     try:
                         parent = obj
                         obj = getattr(obj,part)
                     except:
                         # Blanket except b/c some badly implemented objects
                         # allow __getattr__ to raise exceptions other than
                         # AttributeError, which then crashes IPython.
                         break
                 else:
                     # If we finish the for loop (no break), we got all members
                     found = 1
                     ospace = nsname
                     if ns == alias_ns:
                         isalias = 1
                     break  # namespace loop
 
         # Try to see if it's magic
         if not found:
             if oname.startswith(self.shell.ESC_MAGIC):
                 oname = oname[1:]
             obj = getattr(self,'magic_'+oname,None)
             if obj is not None:
                 found = 1
                 ospace = 'IPython internal'
                 ismagic = 1
 
         # Last try: special-case some literals like '', [], {}, etc:
         if not found and oname_head in ["''",'""','[]','{}','()']:
             obj = eval(oname_head)
             found = 1
             ospace = 'Interactive'
             
         return {'found':found, 'obj':obj, 'namespace':ospace,
                 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
     
     def arg_err(self,func):
         """Print docstring if incorrect arguments were passed"""
         print 'Error in arguments:'
         print OInspect.getdoc(func)
 
     def format_latex(self,strng):
         """Format a string for latex inclusion."""
 
         # Characters that need to be escaped for latex:
         escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
         # Magic command names as headers:
         cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
                                  re.MULTILINE)
         # Magic commands 
         cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
                             re.MULTILINE)
         # Paragraph continue
         par_re = re.compile(r'\\$',re.MULTILINE)
 
         # The "\n" symbol
         newline_re = re.compile(r'\\n')
 
         # Now build the string for output:
         #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
         strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
                                 strng)
         strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
         strng = par_re.sub(r'\\\\',strng)
         strng = escape_re.sub(r'\\\1',strng)
         strng = newline_re.sub(r'\\textbackslash{}n',strng)
         return strng
 
     def format_screen(self,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 parse_options(self,arg_str,opt_str,*long_opts,**kw):
         """Parse options passed to an argument string.
 
         The interface is similar to that of getopt(), but it returns back a
         Struct with the options as keys and the stripped argument string still
         as a string.
 
         arg_str is quoted as a true sys.argv vector by using shlex.split.
         This allows us to easily expand variables, glob files, quote
         arguments, etc.
 
         Options:
           -mode: default 'string'. If given as 'list', the argument string is
           returned as a list (split on whitespace) instead of a string.
 
           -list_all: put all option values in lists. Normally only options
           appearing more than once are put in a list.
 
           -posix (True): whether to split the input line in POSIX mode or not,
           as per the conventions outlined in the shlex module from the
           standard library."""
  
         # inject default options at the beginning of the input line
         caller = sys._getframe(1).f_code.co_name.replace('magic_','')
         arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
         
         mode = kw.get('mode','string')
         if mode not in ['string','list']:
             raise ValueError,'incorrect mode given: %s' % mode
         # Get options
         list_all = kw.get('list_all',0)
         posix = kw.get('posix',True)
 
         # Check if we have more than one argument to warrant extra processing:
         odict = {}  # Dictionary with options
         args = arg_str.split()
         if len(args) >= 1:
             # If the list of inputs only has 0 or 1 thing in it, there's no
             # need to look for options
             argv = arg_split(arg_str,posix)
             # Do regular option processing
             try:
                 opts,args = getopt(argv,opt_str,*long_opts)
             except GetoptError,e:
                 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str, 
                                         " ".join(long_opts)))
             for o,a in opts:
                 if o.startswith('--'):
                     o = o[2:]
                 else:
                     o = o[1:]
                 try:
                     odict[o].append(a)
                 except AttributeError:
                     odict[o] = [odict[o],a]
                 except KeyError:
                     if list_all:
                         odict[o] = [a]
                     else:
                         odict[o] = a
 
         # Prepare opts,args for return
         opts = Struct(odict)
         if mode == 'string':
             args = ' '.join(args)
 
         return opts,args
     
     #......................................................................
     # And now the actual magic functions
 
     # Functions for IPython shell work (vars,funcs, config, etc)
     def magic_lsmagic(self, parameter_s = ''):
         """List currently available magic functions."""
         mesc = self.shell.ESC_MAGIC
         print 'Available magic functions:\n'+mesc+\
               ('  '+mesc).join(self.lsmagic())
         print '\n' + Magic.auto_status[self.shell.rc.automagic]
         return None
         
     def magic_magic(self, parameter_s = ''):
         """Print information about the magic function system.
         
         Supported formats: -latex, -brief, -rest        
         """
 
         mode = ''
         try:
             if parameter_s.split()[0] == '-latex':
                 mode = 'latex'
             if parameter_s.split()[0] == '-brief':
                 mode = 'brief'
             if parameter_s.split()[0] == '-rest':
                 mode = 'rest'
                 rest_docs = []
         except:
             pass
 
         magic_docs = []
         for fname in self.lsmagic():
             mname = 'magic_' + fname
             for space in (Magic,self,self.__class__):
                 try:
                     fn = space.__dict__[mname]
                 except KeyError:
                     pass
                 else:
                     break
             if mode == 'brief':
                 # only first line
                 if fn.__doc__:                    
                     fndoc = fn.__doc__.split('\n',1)[0]
                 else:
                     fndoc = 'No documentation'
             else:
-                fndoc = fn.__doc__.rstrip()
+                if fn.__doc__:
+                    fndoc = fn.__doc__.rstrip()       
+                else:
+                    fndoc = 'No documentation'
+                
                 
             if mode == 'rest':
                 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
                                                     fname,fndoc))
                 
             else:
                 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
                                                     fname,fndoc))
                 
         magic_docs = ''.join(magic_docs)
 
         if mode == 'rest':
             return "".join(rest_docs)
         
         if mode == 'latex':
             print self.format_latex(magic_docs)
             return
         else:
             magic_docs = self.format_screen(magic_docs)
         if mode == 'brief':
             return magic_docs
         
         outmsg = """
 IPython's 'magic' functions
 ===========================
 
 The magic function system provides a series of functions which allow you to
 control the behavior of IPython itself, plus a lot of system-type
 features. All these functions are prefixed with a % character, but parameters
 are given without parentheses or quotes.
 
 NOTE: If you have 'automagic' enabled (via the command line option or with the
 %automagic function), you don't need to type in the % explicitly.  By default,
 IPython ships with automagic on, so you should only rarely need the % escape.
 
 Example: typing '%cd mydir' (without the quotes) changes you working directory
 to 'mydir', if it exists.
 
 You can define your own magic functions to extend the system. See the supplied
 ipythonrc and example-magic.py files for details (in your ipython
 configuration directory, typically $HOME/.ipython/).
 
 You can also define your own aliased names for magic functions. In your
 ipythonrc file, placing a line like:
 
   execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
 
 will define %pf as a new name for %profile.
 
 You can also call magics in code using the ipmagic() function, which IPython
 automatically adds to the builtin namespace.  Type 'ipmagic?' for details.
 
 For a list of the available magic functions, use %lsmagic. For a description
 of any of them, type %magic_name?, e.g. '%cd?'.
 
 Currently the magic system has the following functions:\n"""
 
         mesc = self.shell.ESC_MAGIC
         outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
                   "\n\n%s%s\n\n%s" % (outmsg,
                                      magic_docs,mesc,mesc,
                                      ('  '+mesc).join(self.lsmagic()),
                                      Magic.auto_status[self.shell.rc.automagic] ) )
 
         page(outmsg,screen_lines=self.shell.rc.screen_length)
   
 
     def magic_autoindent(self, parameter_s = ''):
         """Toggle autoindent on/off (if available)."""
 
         self.shell.set_autoindent()
         print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
 
 
     def magic_automagic(self, parameter_s = ''):
         """Make magic functions callable without having to type the initial %.
 
         Without argumentsl toggles on/off (when off, you must call it as
         %automagic, of course).  With arguments it sets the value, and you can
         use any of (case insensitive):
 
          - on,1,True: to activate
 
          - off,0,False: to deactivate.
 
         Note that magic functions have lowest priority, so if there's a
         variable whose name collides with that of a magic fn, automagic won't
         work for that function (you get the variable instead). However, if you
         delete the variable (del var), the previously shadowed magic function
         becomes visible to automagic again."""
 
         rc = self.shell.rc
         arg = parameter_s.lower()
         if parameter_s in ('on','1','true'):
             rc.automagic = True
         elif parameter_s in ('off','0','false'):
             rc.automagic = False
         else:
             rc.automagic = not rc.automagic
         print '\n' + Magic.auto_status[rc.automagic]
 
     @testdec.skip_doctest
     def magic_autocall(self, parameter_s = ''):
         """Make functions callable without having to type parentheses.
 
         Usage:
 
            %autocall [mode]
 
         The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
         value is toggled on and off (remembering the previous state).
 
         In more detail, these values mean:
 
         0 -> fully disabled
 
         1 -> active, but do not apply if there are no arguments on the line.
 
         In this mode, you get:
 
         In [1]: callable
         Out[1]: <built-in function callable>
 
         In [2]: callable 'hello'
         ------> callable('hello')
         Out[2]: False
 
         2 -> Active always.  Even if no arguments are present, the callable
         object is called:
 
         In [2]: float
         ------> float()
         Out[2]: 0.0
 
         Note that even with autocall off, you can still use '/' at the start of
         a line to treat the first argument on the command line as a function
         and add parentheses to it:
 
         In [8]: /str 43
         ------> str(43)
         Out[8]: '43'
 
         # all-random (note for auto-testing)
         """
 
         rc = self.shell.rc
 
         if parameter_s:
             arg = int(parameter_s)
         else:
             arg = 'toggle'
 
         if not arg in (0,1,2,'toggle'):
             error('Valid modes: (0->Off, 1->Smart, 2->Full')
             return
 
         if arg in (0,1,2):
             rc.autocall = arg
         else: # toggle
             if rc.autocall:
                 self._magic_state.autocall_save = rc.autocall
                 rc.autocall = 0
             else:
                 try:
                     rc.autocall = self._magic_state.autocall_save
                 except AttributeError:
                     rc.autocall = self._magic_state.autocall_save = 1
 
         print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
 
     def magic_system_verbose(self, parameter_s = ''):
         """Set verbose printing of system calls.
 
         If called without an argument, act as a toggle"""
 
         if parameter_s:
             val = bool(eval(parameter_s))
         else:
             val = None
             
         self.shell.rc_set_toggle('system_verbose',val)
         print "System verbose printing is:",\
               ['OFF','ON'][self.shell.rc.system_verbose]
 
 
     def magic_page(self, parameter_s=''):
         """Pretty print the object and display it through a pager.
         
         %page [options] OBJECT
 
         If no object is given, use _ (last output).
         
         Options:
 
           -r: page str(object), don't pretty-print it."""
 
         # After a function contributed by Olivier Aubert, slightly modified.
 
         # Process options/args
         opts,args = self.parse_options(parameter_s,'r')
         raw = 'r' in opts
 
         oname = args and args or '_'
         info = self._ofind(oname)
         if info['found']:
             txt = (raw and str or pformat)( info['obj'] )
             page(txt)
         else:
             print 'Object `%s` not found' % oname
 
     def magic_profile(self, parameter_s=''):
         """Print your currently active IPyhton profile."""
         if self.shell.rc.profile:
             printpl('Current IPython profile: $self.shell.rc.profile.')
         else:
             print 'No profile active.'
 
     def magic_pinfo(self, parameter_s='', namespaces=None):
         """Provide detailed information about an object.
     
         '%pinfo object' is just a synonym for object? or ?object."""
     
         #print 'pinfo par: <%s>' % parameter_s  # dbg
     
         
         # detail_level: 0 -> obj? , 1 -> obj??
         detail_level = 0
         # We need to detect if we got called as 'pinfo pinfo foo', which can
         # happen if the user types 'pinfo foo?' at the cmd line.
         pinfo,qmark1,oname,qmark2 = \
                re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
         if pinfo or qmark1 or qmark2:
             detail_level = 1
         if "*" in oname:
             self.magic_psearch(oname)
         else:
             self._inspect('pinfo', oname, detail_level=detail_level,
                           namespaces=namespaces)
 
     def magic_pdef(self, parameter_s='', namespaces=None):
         """Print the definition header for any callable object.
 
         If the object is a class, print the constructor information."""
         self._inspect('pdef',parameter_s, namespaces)
 
     def magic_pdoc(self, parameter_s='', namespaces=None):
         """Print the docstring for an object.
 
         If the given object is a class, it will print both the class and the
         constructor docstrings."""
         self._inspect('pdoc',parameter_s, namespaces)
 
     def magic_psource(self, parameter_s='', namespaces=None):
         """Print (or run through pager) the source code for an object."""
         self._inspect('psource',parameter_s, namespaces)
 
     def magic_pfile(self, parameter_s=''):
         """Print (or run through pager) the file where an object is defined.
 
         The file opens at the line where the object definition begins. IPython
         will honor the environment variable PAGER if set, and otherwise will
         do its best to print the file in a convenient form.
 
         If the given argument is not an object currently defined, IPython will
         try to interpret it as a filename (automatically adding a .py extension
         if needed). You can thus use %pfile as a syntax highlighting code
         viewer."""
 
         # first interpret argument as an object name
         out = self._inspect('pfile',parameter_s)
         # if not, try the input as a filename
         if out == 'not found':
             try:
                 filename = get_py_filename(parameter_s)
             except IOError,msg:
                 print msg
                 return
             page(self.shell.inspector.format(file(filename).read()))
 
     def _inspect(self,meth,oname,namespaces=None,**kw):
         """Generic interface to the inspector system.
 
         This function is meant to be called by pdef, pdoc & friends."""
 
         #oname = oname.strip()
         #print '1- oname: <%r>' % oname  # dbg
         try:
             oname = oname.strip().encode('ascii')
             #print '2- oname: <%r>' % oname  # dbg
         except UnicodeEncodeError:
             print 'Python identifiers can only contain ascii characters.'
             return 'not found'
             
         info = Struct(self._ofind(oname, namespaces))
         
         if info.found:
             try:
                 IPython.generics.inspect_object(info.obj)
                 return
             except IPython.ipapi.TryNext:
                 pass
             # Get the docstring of the class property if it exists.
             path = oname.split('.')
             root = '.'.join(path[:-1])
             if info.parent is not None:
                 try:
                     target = getattr(info.parent, '__class__') 
                     # The object belongs to a class instance. 
                     try: 
                         target = getattr(target, path[-1])
                         # The class defines the object. 
                         if isinstance(target, property):
                             oname = root + '.__class__.' + path[-1]
                             info = Struct(self._ofind(oname))
                     except AttributeError: pass
                 except AttributeError: pass
                         
             pmethod = getattr(self.shell.inspector,meth)
             formatter = info.ismagic and self.format_screen or None
             if meth == 'pdoc':
                 pmethod(info.obj,oname,formatter)
             elif meth == 'pinfo':
                 pmethod(info.obj,oname,formatter,info,**kw)
             else:
                 pmethod(info.obj,oname)
         else:
             print 'Object `%s` not found.' % oname
             return 'not found'  # so callers can take other action
         
     def magic_psearch(self, parameter_s=''):
         """Search for object in namespaces by wildcard.
 
         %psearch [options] PATTERN [OBJECT TYPE]
 
         Note: ? can be used as a synonym for %psearch, at the beginning or at
         the end: both a*? and ?a* are equivalent to '%psearch a*'.  Still, the
         rest of the command line must be unchanged (options come first), so
         for example the following forms are equivalent
 
         %psearch -i a* function
         -i a* function?
         ?-i a* function
 
         Arguments:
         
           PATTERN
 
           where PATTERN is a string containing * as a wildcard similar to its
           use in a shell.  The pattern is matched in all namespaces on the
           search path. By default objects starting with a single _ are not
           matched, many IPython generated objects have a single
           underscore. The default is case insensitive matching. Matching is
           also done on the attributes of objects and not only on the objects
           in a module.
 
           [OBJECT TYPE]
 
           Is the name of a python type from the types module. The name is
           given in lowercase without the ending type, ex. StringType is
           written string. By adding a type here only objects matching the
           given type are matched. Using all here makes the pattern match all
           types (this is the default).
 
         Options:
 
           -a: makes the pattern match even objects whose names start with a
           single underscore.  These names are normally ommitted from the
           search.
 
           -i/-c: make the pattern case insensitive/sensitive.  If neither of
           these options is given, the default is read from your ipythonrc
           file.  The option name which sets this value is
           'wildcards_case_sensitive'.  If this option is not specified in your
           ipythonrc file, IPython's internal default is to do a case sensitive
           search.
 
           -e/-s NAMESPACE: exclude/search a given namespace.  The pattern you
           specifiy can be searched in any of the following namespaces:
           'builtin', 'user', 'user_global','internal', 'alias', where
           'builtin' and 'user' are the search defaults.  Note that you should
           not use quotes when specifying namespaces.
 
           'Builtin' contains the python module builtin, 'user' contains all
           user data, 'alias' only contain the shell aliases and no python
           objects, 'internal' contains objects used by IPython.  The
           'user_global' namespace is only used by embedded IPython instances,
           and it contains module-level globals.  You can add namespaces to the
           search with -s or exclude them with -e (these options can be given
           more than once).
     
         Examples:
        
         %psearch a*            -> objects beginning with an a
         %psearch -e builtin a* -> objects NOT in the builtin space starting in a
         %psearch a* function   -> all functions beginning with an a
         %psearch re.e*         -> objects beginning with an e in module re
         %psearch r*.e*         -> objects that start with e in modules starting in r
         %psearch r*.* string   -> all strings in modules beginning with r
 
         Case sensitve search:
        
         %psearch -c a*         list all object beginning with lower case a
 
         Show objects beginning with a single _:
        
         %psearch -a _*         list objects beginning with a single underscore"""
         try:
             parameter_s = parameter_s.encode('ascii')
         except UnicodeEncodeError:
             print 'Python identifiers can only contain ascii characters.'
             return
 
         # default namespaces to be searched
         def_search = ['user','builtin']
 
         # Process options/args
         opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
         opt = opts.get
         shell = self.shell
         psearch = shell.inspector.psearch
 
         # select case options
         if opts.has_key('i'):
             ignore_case = True
         elif opts.has_key('c'):
             ignore_case = False
         else:
             ignore_case = not shell.rc.wildcards_case_sensitive
 
         # Build list of namespaces to search from user options
         def_search.extend(opt('s',[]))
         ns_exclude = ns_exclude=opt('e',[])
         ns_search = [nm for nm in def_search if nm not in ns_exclude]
         
         # Call the actual search
         try:
             psearch(args,shell.ns_table,ns_search,
                     show_all=opt('a'),ignore_case=ignore_case)
         except:
             shell.showtraceback()
 
     def magic_who_ls(self, parameter_s=''):
         """Return a sorted list of all interactive variables.
 
         If arguments are given, only variables of types matching these
         arguments are returned."""
 
         user_ns = self.shell.user_ns
         internal_ns = self.shell.internal_ns
         user_config_ns = self.shell.user_config_ns
         out = []
         typelist = parameter_s.split()
 
         for i in user_ns:
             if not (i.startswith('_') or i.startswith('_i')) \
                    and not (i in internal_ns or i in user_config_ns):
                 if typelist:
                     if type(user_ns[i]).__name__ in typelist:
                         out.append(i)
                 else:
                     out.append(i)
         out.sort()
         return out
         
     def magic_who(self, parameter_s=''):
         """Print all interactive variables, with some minimal formatting.
 
         If any arguments are given, only variables whose type matches one of
         these are printed.  For example:
 
           %who function str
 
         will only list functions and strings, excluding all other types of
         variables.  To find the proper type names, simply use type(var) at a
         command line to see how python prints type names.  For example:
 
           In [1]: type('hello')\\
           Out[1]: <type 'str'>
 
         indicates that the type name for strings is 'str'.
 
         %who always excludes executed names loaded through your configuration
         file and things which are internal to IPython.
 
         This is deliberate, as typically you may load many modules and the
         purpose of %who is to show you only what you've manually defined."""
 
         varlist = self.magic_who_ls(parameter_s)
         if not varlist:
             if parameter_s:
                 print 'No variables match your requested type.'
             else:
                 print 'Interactive namespace is empty.'
             return
 
         # if we have variables, move on...
         count = 0
         for i in varlist:
             print i+'\t',
             count += 1
             if count > 8:
                 count = 0
                 print
         print
 
     def magic_whos(self, parameter_s=''):
         """Like %who, but gives some extra information about each variable.
 
         The same type filtering of %who can be applied here.
 
         For all variables, the type is printed. Additionally it prints:
         
           - For {},[],(): their length.
 
           - For numpy and Numeric arrays, a summary with shape, number of
           elements, typecode and size in memory.
 
           - Everything else: a string representation, snipping their middle if
           too long."""
         
         varnames = self.magic_who_ls(parameter_s)
         if not varnames:
             if parameter_s:
                 print 'No variables match your requested type.'
             else:
                 print 'Interactive namespace is empty.'
             return
 
         # if we have variables, move on...
 
         # for these types, show len() instead of data:
         seq_types = [types.DictType,types.ListType,types.TupleType]
 
         # for numpy/Numeric arrays, display summary info
         try:
             import numpy
         except ImportError:
             ndarray_type = None
         else:
             ndarray_type = numpy.ndarray.__name__
         try:
             import Numeric
         except ImportError:
             array_type = None
         else:
             array_type = Numeric.ArrayType.__name__
 
         # Find all variable names and types so we can figure out column sizes
         def get_vars(i):
             return self.shell.user_ns[i]
         
         # some types are well known and can be shorter
         abbrevs = {'IPython.macro.Macro' : 'Macro'}
         def type_name(v):
             tn = type(v).__name__
             return abbrevs.get(tn,tn)
             
         varlist = map(get_vars,varnames)
 
         typelist = []
         for vv in varlist:
             tt = type_name(vv)
 
             if tt=='instance':
                 typelist.append( abbrevs.get(str(vv.__class__),
                                              str(vv.__class__)))
             else:
                 typelist.append(tt)
 
         # column labels and # of spaces as separator
         varlabel = 'Variable'
         typelabel = 'Type'
         datalabel = 'Data/Info'
         colsep = 3
         # variable format strings
         vformat    = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
         vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
         aformat    = "%s: %s elems, type `%s`, %s bytes"
         # find the size of the columns to format the output nicely
         varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
         typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
         # table header
         print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
               ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
         # and the table itself
         kb = 1024
         Mb = 1048576  # kb**2
         for vname,var,vtype in zip(varnames,varlist,typelist):
             print itpl(vformat),
             if vtype in seq_types:
                 print len(var)
             elif vtype in [array_type,ndarray_type]:
                 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
                 if vtype==ndarray_type:
                     # numpy
                     vsize  = var.size
                     vbytes = vsize*var.itemsize
                     vdtype = var.dtype
                 else:
                     # Numeric
                     vsize  = Numeric.size(var)
                     vbytes = vsize*var.itemsize()
                     vdtype = var.typecode()
                     
                 if vbytes < 100000:
                     print aformat % (vshape,vsize,vdtype,vbytes)
                 else:
                     print aformat % (vshape,vsize,vdtype,vbytes),
                     if vbytes < Mb:
                         print '(%s kb)' % (vbytes/kb,)
                     else:
                         print '(%s Mb)' % (vbytes/Mb,)
             else:
                 try:
                     vstr = str(var)
                 except UnicodeEncodeError:
                     vstr = unicode(var).encode(sys.getdefaultencoding(),
                                                'backslashreplace')
                 vstr = vstr.replace('\n','\\n')
                 if len(vstr) < 50:
                     print vstr
                 else:
                     printpl(vfmt_short)
                 
     def magic_reset(self, parameter_s=''):
         """Resets the namespace by removing all names defined by the user.
 
         Input/Output history are left around in case you need them."""
 
         ans = self.shell.ask_yes_no(
           "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
         if not ans:
             print 'Nothing done.'
             return
         user_ns = self.shell.user_ns
         for i in self.magic_who_ls():
             del(user_ns[i])
             
         # Also flush the private list of module references kept for script
         # execution protection
         self.shell._user_main_modules[:] = []
 
     def magic_logstart(self,parameter_s=''):
         """Start logging anywhere in a session.
 
         %logstart [-o|-r|-t] [log_name [log_mode]]
 
         If no name is given, it defaults to a file named 'ipython_log.py' in your
         current directory, in 'rotate' mode (see below).
 
         '%logstart name' saves to file 'name' in 'backup' mode.  It saves your
         history up to that point and then continues logging.
 
         %logstart takes a second optional parameter: logging mode. This can be one
         of (note that the modes are given unquoted):\\
           append: well, that says it.\\
           backup: rename (if exists) to name~ and start name.\\
           global: single logfile in your home dir, appended to.\\
           over  : overwrite existing log.\\
           rotate: create rotating logs name.1~, name.2~, etc.
 
         Options:
 
           -o: log also IPython's output.  In this mode, all commands which
           generate an Out[NN] prompt are recorded to the logfile, right after
           their corresponding input line.  The output lines are always
           prepended with a '#[Out]# ' marker, so that the log remains valid
           Python code.
 
           Since this marker is always the same, filtering only the output from
           a log is very easy, using for example a simple awk call:
 
             awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
 
           -r: log 'raw' input.  Normally, IPython's logs contain the processed
           input, so that user lines are logged in their final form, converted
           into valid Python.  For example, %Exit is logged as
           '_ip.magic("Exit").  If the -r flag is given, all input is logged
           exactly as typed, with no transformations applied.
 
           -t: put timestamps before each input line logged (these are put in
           comments)."""
         
         opts,par = self.parse_options(parameter_s,'ort')
         log_output = 'o' in opts
         log_raw_input = 'r' in opts
         timestamp = 't' in opts
 
         rc = self.shell.rc
         logger = self.shell.logger
 
         # if no args are given, the defaults set in the logger constructor by
         # ipytohn remain valid
         if par:
             try:
                 logfname,logmode = par.split()
             except:
                 logfname = par
                 logmode = 'backup'
         else:
             logfname = logger.logfname
             logmode = logger.logmode
         # put logfname into rc struct as if it had been called on the command
         # line, so it ends up saved in the log header Save it in case we need
         # to restore it...
         old_logfile = rc.opts.get('logfile','')  
         if logfname:
             logfname = os.path.expanduser(logfname)
         rc.opts.logfile = logfname
         loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
         try:
             started  = logger.logstart(logfname,loghead,logmode,
                                        log_output,timestamp,log_raw_input)
         except:
             rc.opts.logfile = old_logfile
             warn("Couldn't start log: %s" % sys.exc_info()[1])
         else:
             # log input history up to this point, optionally interleaving
             # output if requested
 
             if timestamp:
                 # disable timestamping for the previous history, since we've
                 # lost those already (no time machine here).
                 logger.timestamp = False
 
             if log_raw_input:
                 input_hist = self.shell.input_hist_raw
             else:
                 input_hist = self.shell.input_hist
                 
             if log_output:
                 log_write = logger.log_write
                 output_hist = self.shell.output_hist
                 for n in range(1,len(input_hist)-1):
                     log_write(input_hist[n].rstrip())
                     if n in output_hist:
                         log_write(repr(output_hist[n]),'output')
             else:
                 logger.log_write(input_hist[1:])
             if timestamp:
                 # re-enable timestamping
                 logger.timestamp = True
                 
             print ('Activating auto-logging. '
                    'Current session state plus future input saved.')
             logger.logstate()
 
     def magic_logstop(self,parameter_s=''):
         """Fully stop logging and close log file.
 
         In order to start logging again, a new %logstart call needs to be made,
         possibly (though not necessarily) with a new filename, mode and other
         options."""
         self.logger.logstop()
 
     def magic_logoff(self,parameter_s=''):
         """Temporarily stop logging.
 
         You must have previously started logging."""
         self.shell.logger.switch_log(0)
         
     def magic_logon(self,parameter_s=''):
         """Restart logging.
 
         This function is for restarting logging which you've temporarily
         stopped with %logoff. For starting logging for the first time, you
         must use the %logstart function, which allows you to specify an
         optional log filename."""
         
         self.shell.logger.switch_log(1)
     
     def magic_logstate(self,parameter_s=''):
         """Print the status of the logging system."""
 
         self.shell.logger.logstate()
         
     def magic_pdb(self, parameter_s=''):
         """Control the automatic calling of the pdb interactive debugger.
 
         Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
         argument it works as a toggle.
 
         When an exception is triggered, IPython can optionally call the
         interactive pdb debugger after the traceback printout. %pdb toggles
         this feature on and off.
 
         The initial state of this feature is set in your ipythonrc
         configuration file (the variable is called 'pdb').
 
         If you want to just activate the debugger AFTER an exception has fired,
         without having to type '%pdb on' and rerunning your code, you can use
         the %debug magic."""
 
         par = parameter_s.strip().lower()
 
         if par:
             try:
                 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
             except KeyError:
                 print ('Incorrect argument. Use on/1, off/0, '
                        'or nothing for a toggle.')
                 return
         else:
             # toggle
             new_pdb = not self.shell.call_pdb
 
         # set on the shell
         self.shell.call_pdb = new_pdb
         print 'Automatic pdb calling has been turned',on_off(new_pdb)
 
     def magic_debug(self, parameter_s=''):
         """Activate the interactive debugger in post-mortem mode.
 
         If an exception has just occurred, this lets you inspect its stack
         frames interactively.  Note that this will always work only on the last
         traceback that occurred, so you must call this quickly after an
         exception that you wish to inspect has fired, because if another one
         occurs, it clobbers the previous one.
 
         If you want IPython to automatically do this on every exception, see
         the %pdb magic for more details.
         """
         
         self.shell.debugger(force=True)
 
     @testdec.skip_doctest
     def magic_prun(self, parameter_s ='',user_mode=1,
                    opts=None,arg_lst=None,prog_ns=None):
 
         """Run a statement through the python code profiler.
 
         Usage:
           %prun [options] statement
 
         The given statement (which doesn't require quote marks) is run via the
         python profiler in a manner similar to the profile.run() function.
         Namespaces are internally managed to work correctly; profile.run
         cannot be used in IPython because it makes certain assumptions about
         namespaces which do not hold under IPython.
 
         Options:
 
         -l <limit>: you can place restrictions on what or how much of the
         profile gets printed. The limit value can be:
 
           * A string: only information for function names containing this string
           is printed.
 
           * An integer: only these many lines are printed.
 
           * A float (between 0 and 1): this fraction of the report is printed
           (for example, use a limit of 0.4 to see the topmost 40% only).
 
         You can combine several limits with repeated use of the option. For
         example, '-l __init__ -l 5' will print only the topmost 5 lines of
         information about class constructors.
 
         -r: return the pstats.Stats object generated by the profiling. This
         object has all the information about the profile in it, and you can
         later use it for further analysis or in other functions.
 
        -s <key>: sort profile by given key. You can provide more than one key
         by using the option several times: '-s key1 -s key2 -s key3...'. The
         default sorting key is 'time'.
 
         The following is copied verbatim from the profile documentation
         referenced below:
 
         When more than one key is provided, additional keys are used as
         secondary criteria when the there is equality in all keys selected
         before them.
         
         Abbreviations can be used for any key names, as long as the
         abbreviation is unambiguous.  The following are the keys currently
         defined:
 
                 Valid Arg       Meaning
                   "calls"      call count
                   "cumulative" cumulative time
                   "file"       file name
                   "module"     file name
                   "pcalls"     primitive call count
                   "line"       line number
                   "name"       function name
                   "nfl"        name/file/line
                   "stdname"    standard name
                   "time"       internal time
 
         Note that all sorts on statistics are in descending order (placing
         most time consuming items first), where as name, file, and line number
         searches are in ascending order (i.e., alphabetical). The subtle
         distinction between "nfl" and "stdname" is that the standard name is a
         sort of the name as printed, which means that the embedded line
         numbers get compared in an odd way.  For example, lines 3, 20, and 40
         would (if the file names were the same) appear in the string order
         "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
         line numbers.  In fact, sort_stats("nfl") is the same as
         sort_stats("name", "file", "line").
 
         -T <filename>: save profile results as shown on screen to a text
         file. The profile is still shown on screen.
 
         -D <filename>: save (via dump_stats) profile statistics to given
         filename. This data is in a format understod by the pstats module, and
         is generated by a call to the dump_stats() method of profile
         objects. The profile is still shown on screen.
 
         If you want to run complete programs under the profiler's control, use
         '%run -p [prof_opts] filename.py [args to program]' where prof_opts
         contains profiler specific options as described here.
         
         You can read the complete documentation for the profile module with::
         
           In [1]: import profile; profile.help()
         """
 
         opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
         # protect user quote marks
         parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
         
         if user_mode:  # regular user call
             opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
                                               list_all=1)
             namespace = self.shell.user_ns
         else:  # called to run a program by %run -p
             try:
                 filename = get_py_filename(arg_lst[0])
             except IOError,msg:
                 error(msg)
                 return
 
             arg_str = 'execfile(filename,prog_ns)'
             namespace = locals()
 
         opts.merge(opts_def)
         
         prof = profile.Profile()
         try:
             prof = prof.runctx(arg_str,namespace,namespace)
             sys_exit = ''
         except SystemExit:
             sys_exit = """*** SystemExit exception caught in code being profiled."""
 
         stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
 
         lims = opts.l
         if lims:
             lims = []  # rebuild lims with ints/floats/strings
             for lim in opts.l:
                 try:
                     lims.append(int(lim))
                 except ValueError:
                     try:
                         lims.append(float(lim))
                     except ValueError:
                         lims.append(lim)
                     
         # Trap output.
         stdout_trap = StringIO()
 
         if hasattr(stats,'stream'):
             # In newer versions of python, the stats object has a 'stream'
             # attribute to write into.
             stats.stream = stdout_trap
             stats.print_stats(*lims)
         else:
             # For older versions, we manually redirect stdout during printing
             sys_stdout = sys.stdout
             try:
                 sys.stdout = stdout_trap
                 stats.print_stats(*lims)
             finally:
                 sys.stdout = sys_stdout
                 
         output = stdout_trap.getvalue()
         output = output.rstrip()
 
         page(output,screen_lines=self.shell.rc.screen_length)
         print sys_exit,
 
         dump_file = opts.D[0]
         text_file = opts.T[0]
         if dump_file:
             prof.dump_stats(dump_file)
             print '\n*** Profile stats marshalled to file',\
                   `dump_file`+'.',sys_exit
         if text_file:
             pfile = file(text_file,'w')
             pfile.write(output)
             pfile.close()
             print '\n*** Profile printout saved to text file',\
                   `text_file`+'.',sys_exit
 
         if opts.has_key('r'):
             return stats
         else:
             return None
 
     @testdec.skip_doctest
     def magic_run(self, parameter_s ='',runner=None):
         """Run the named file inside IPython as a program.
 
         Usage:\\
           %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
         
         Parameters after the filename are passed as command-line arguments to
         the program (put in sys.argv). Then, control returns to IPython's
         prompt.
 
         This is similar to running at a system prompt:\\
           $ python file args\\
         but with the advantage of giving you IPython's tracebacks, and of
         loading all variables into your interactive namespace for further use
         (unless -p is used, see below).
 
         The file is executed in a namespace initially consisting only of
         __name__=='__main__' and sys.argv constructed as indicated. It thus
         sees its environment as if it were being run as a stand-alone program
         (except for sharing global objects such as previously imported
         modules). But after execution, the IPython interactive namespace gets
         updated with all variables defined in the program (except for __name__
         and sys.argv). This allows for very convenient loading of code for
         interactive work, while giving each program a 'clean sheet' to run in.
 
         Options:
         
         -n: __name__ is NOT set to '__main__', but to the running file's name
         without extension (as python does under import).  This allows running
         scripts and reloading the definitions in them without calling code
         protected by an ' if __name__ == "__main__" ' clause.
 
         -i: run the file in IPython's namespace instead of an empty one. This
         is useful if you are experimenting with code written in a text editor
         which depends on variables defined interactively.
 
         -e: ignore sys.exit() calls or SystemExit exceptions in the script
         being run.  This is particularly useful if IPython is being used to
         run unittests, which always exit with a sys.exit() call.  In such
         cases you are interested in the output of the test results, not in
         seeing a traceback of the unittest module.
 
         -t: print timing information at the end of the run.  IPython will give
         you an estimated CPU time consumption for your script, which under
         Unix uses the resource module to avoid the wraparound problems of
         time.clock().  Under Unix, an estimate of time spent on system tasks
         is also given (for Windows platforms this is reported as 0.0).
 
         If -t is given, an additional -N<N> option can be given, where <N>
         must be an integer indicating how many times you want the script to
         run.  The final timing report will include total and per run results.
 
         For example (testing the script uniq_stable.py):
 
             In [1]: run -t uniq_stable
 
             IPython CPU timings (estimated):\\
               User  :    0.19597 s.\\
               System:        0.0 s.\\
 
             In [2]: run -t -N5 uniq_stable
 
             IPython CPU timings (estimated):\\
             Total runs performed: 5\\
               Times :      Total       Per run\\
               User  :   0.910862 s,  0.1821724 s.\\
               System:        0.0 s,        0.0 s.
 
         -d: run your program under the control of pdb, the Python debugger.
         This allows you to execute your program step by step, watch variables,
         etc.  Internally, what IPython does is similar to calling:
         
           pdb.run('execfile("YOURFILENAME")')
 
         with a breakpoint set on line 1 of your file.  You can change the line
         number for this automatic breakpoint to be <N> by using the -bN option
         (where N must be an integer).  For example:
 
           %run -d -b40 myscript
 
         will set the first breakpoint at line 40 in myscript.py.  Note that
         the first breakpoint must be set on a line which actually does
         something (not a comment or docstring) for it to stop execution.
 
         When the pdb debugger starts, you will see a (Pdb) prompt.  You must
         first enter 'c' (without qoutes) to start execution up to the first
         breakpoint.
 
         Entering 'help' gives information about the use of the debugger.  You
         can easily see pdb's full documentation with "import pdb;pdb.help()"
         at a prompt.
 
         -p: run program under the control of the Python profiler module (which
         prints a detailed report of execution times, function calls, etc).
 
         You can pass other options after -p which affect the behavior of the
         profiler itself. See the docs for %prun for details.
 
         In this mode, the program's variables do NOT propagate back to the
         IPython interactive namespace (because they remain in the namespace
         where the profiler executes them).
 
         Internally this triggers a call to %prun, see its documentation for
         details on the options available specifically for profiling.
 
         There is one special usage for which the text above doesn't apply:
         if the filename ends with .ipy, the file is run as ipython script,
         just as if the commands were written on IPython prompt.
         """
 
         # get arguments and set sys.argv for program to be run.
         opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
                                           mode='list',list_all=1)
 
         try:
             filename = get_py_filename(arg_lst[0])
         except IndexError:
             warn('you must provide at least a filename.')
             print '\n%run:\n',OInspect.getdoc(self.magic_run)
             return
         except IOError,msg:
             error(msg)
             return
 
         if filename.lower().endswith('.ipy'):
             self.api.runlines(open(filename).read())
             return
         
         # Control the response to exit() calls made by the script being run
         exit_ignore = opts.has_key('e')
         
         # Make sure that the running script gets a proper sys.argv as if it
         # were run from a system shell.
         save_argv = sys.argv # save it for later restoring
         sys.argv = [filename]+ arg_lst[1:]  # put in the proper filename
 
         if opts.has_key('i'):
             # Run in user's interactive namespace
             prog_ns = self.shell.user_ns
             __name__save = self.shell.user_ns['__name__']
             prog_ns['__name__'] = '__main__'
             main_mod = FakeModule(prog_ns)
         else:
             # Run in a fresh, empty namespace
             if opts.has_key('n'):
                 name = os.path.splitext(os.path.basename(filename))[0]
             else:
                 name = '__main__'
             main_mod = FakeModule()
             prog_ns = main_mod.__dict__
             prog_ns['__name__'] = name
             # The shell MUST hold a reference to main_mod so after %run exits,
             # the python deletion mechanism doesn't zero it out (leaving
             # dangling references)
             self.shell._user_main_modules.append(main_mod)
 
         # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
         # set the __file__ global in the script's namespace
         prog_ns['__file__'] = filename
 
         # pickle fix.  See iplib for an explanation.  But we need to make sure
         # that, if we overwrite __main__, we replace it at the end
         main_mod_name = prog_ns['__name__']
 
         if main_mod_name == '__main__':
             restore_main = sys.modules['__main__']
         else:
             restore_main = False
 
         # This needs to be undone at the end to prevent holding references to
         # every single object ever created.
         sys.modules[main_mod_name] = main_mod
         
         stats = None
         try:
             self.shell.savehist()
 
             if opts.has_key('p'):
                 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
             else:
                 if opts.has_key('d'):
                     deb = Debugger.Pdb(self.shell.rc.colors)
                     # reset Breakpoint state, which is moronically kept
                     # in a class
                     bdb.Breakpoint.next = 1
                     bdb.Breakpoint.bplist = {}
                     bdb.Breakpoint.bpbynumber = [None]
                     # Set an initial breakpoint to stop execution
                     maxtries = 10
                     bp = int(opts.get('b',[1])[0])
                     checkline = deb.checkline(filename,bp)
                     if not checkline:
                         for bp in range(bp+1,bp+maxtries+1):
                             if deb.checkline(filename,bp):
                                 break
                         else:
                             msg = ("\nI failed to find a valid line to set "
                                    "a breakpoint\n"
                                    "after trying up to line: %s.\n"
                                    "Please set a valid breakpoint manually "
                                    "with the -b option." % bp)
                             error(msg)
                             return
                     # if we find a good linenumber, set the breakpoint
                     deb.do_break('%s:%s' % (filename,bp))
                     # Start file run
                     print "NOTE: Enter 'c' at the",
                     print "%s prompt to start your script." % deb.prompt
                     try:
                         deb.run('execfile("%s")' % filename,prog_ns)
                         
                     except:
                         etype, value, tb = sys.exc_info()
                         # Skip three frames in the traceback: the %run one,
                         # one inside bdb.py, and the command-line typed by the
                         # user (run by exec in pdb itself).
                         self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
                 else:
                     if runner is None:
                         runner = self.shell.safe_execfile
                     if opts.has_key('t'):
                         # timed execution
                         try:
                             nruns = int(opts['N'][0])
                             if nruns < 1:
                                 error('Number of runs must be >=1')
                                 return
                         except (KeyError):
                             nruns = 1
                         if nruns == 1:
                             t0 = clock2()
                             runner(filename,prog_ns,prog_ns,
                                    exit_ignore=exit_ignore)
                             t1 = clock2()
                             t_usr = t1[0]-t0[0]
                             t_sys = t1[1]-t1[1]
                             print "\nIPython CPU timings (estimated):"
                             print "  User  : %10s s." % t_usr
                             print "  System: %10s s." % t_sys
                         else:
                             runs = range(nruns)
                             t0 = clock2()
                             for nr in runs:
                                 runner(filename,prog_ns,prog_ns,
                                        exit_ignore=exit_ignore)
                             t1 = clock2()
                             t_usr = t1[0]-t0[0]
                             t_sys = t1[1]-t1[1]
                             print "\nIPython CPU timings (estimated):"
                             print "Total runs performed:",nruns
                             print "  Times : %10s    %10s" % ('Total','Per run')
                             print "  User  : %10s s, %10s s." % (t_usr,t_usr/nruns)
                             print "  System: %10s s, %10s s." % (t_sys,t_sys/nruns)
                             
                     else:
                         # regular execution
                         runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
                 if opts.has_key('i'):
                     self.shell.user_ns['__name__'] = __name__save
                 else:
                     # update IPython interactive namespace
                     del prog_ns['__name__']
                     self.shell.user_ns.update(prog_ns)
         finally:
             # Ensure key global structures are restored
             sys.argv = save_argv
             if restore_main:
                 sys.modules['__main__'] = restore_main
             else:
                 # Remove from sys.modules the reference to main_mod we'd
                 # added.  Otherwise it will trap references to objects
                 # contained therein.
                 del sys.modules[main_mod_name]
             self.shell.reloadhist()
                 
         return stats
 
     def magic_runlog(self, parameter_s =''):
         """Run files as logs.
 
         Usage:\\
           %runlog file1 file2 ...
 
         Run the named files (treating them as log files) in sequence inside
         the interpreter, and return to the prompt.  This is much slower than
         %run because each line is executed in a try/except block, but it
         allows running files with syntax errors in them.
 
         Normally IPython will guess when a file is one of its own logfiles, so
         you can typically use %run even for logs. This shorthand allows you to
         force any file to be treated as a log file."""
 
         for f in parameter_s.split():
             self.shell.safe_execfile(f,self.shell.user_ns,
                                      self.shell.user_ns,islog=1)
 
     @testdec.skip_doctest
     def magic_timeit(self, parameter_s =''):
         """Time execution of a Python statement or expression
 
         Usage:\\
           %timeit [-n<N> -r<R> [-t|-c]] statement
 
         Time execution of a Python statement or expression using the timeit
         module.
 
         Options:
         -n<N>: execute the given statement <N> times in a loop. If this value
         is not given, a fitting value is chosen. 
         
         -r<R>: repeat the loop iteration <R> times and take the best result.
         Default: 3
         
         -t: use time.time to measure the time, which is the default on Unix.
         This function measures wall time.
         
         -c: use time.clock to measure the time, which is the default on
         Windows and measures wall time. On Unix, resource.getrusage is used
         instead and returns the CPU user time.
 
         -p<P>: use a precision of <P> digits to display the timing result.
         Default: 3
 
         
         Examples:
 
           In [1]: %timeit pass
           10000000 loops, best of 3: 53.3 ns per loop
 
           In [2]: u = None
 
           In [3]: %timeit u is None
           10000000 loops, best of 3: 184 ns per loop
 
           In [4]: %timeit -r 4 u == None
           1000000 loops, best of 4: 242 ns per loop
 
           In [5]: import time
 
           In [6]: %timeit -n1 time.sleep(2)
           1 loops, best of 3: 2 s per loop
           
 
         The times reported by %timeit will be slightly higher than those
         reported by the timeit.py script when variables are accessed. This is
         due to the fact that %timeit executes the statement in the namespace
         of the shell, compared with timeit.py, which uses a single setup
         statement to import function or create variables. Generally, the bias
         does not matter as long as results from timeit.py are not mixed with
         those from %timeit."""
 
         import timeit
         import math
 
         units = [u"s", u"ms", u"\xb5s", u"ns"]
         scaling = [1, 1e3, 1e6, 1e9]
 
         opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
                                         posix=False)
         if stmt == "":
             return
         timefunc = timeit.default_timer
         number = int(getattr(opts, "n", 0))
         repeat = int(getattr(opts, "r", timeit.default_repeat))
         precision = int(getattr(opts, "p", 3))
         if hasattr(opts, "t"):
             timefunc = time.time
         if hasattr(opts, "c"):
             timefunc = clock
 
         timer = timeit.Timer(timer=timefunc)
         # this code has tight coupling to the inner workings of timeit.Timer,
         # but is there a better way to achieve that the code stmt has access
         # to the shell namespace?
 
         src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
                                  'setup': "pass"}
         # Track compilation time so it can be reported if too long
         # Minimum time above which compilation time will be reported
         tc_min = 0.1
         
         t0 = clock()
         code = compile(src, "<magic-timeit>", "exec")
         tc = clock()-t0
         
         ns = {}
         exec code in self.shell.user_ns, ns
         timer.inner = ns["inner"]
         
         if number == 0:
             # determine number so that 0.2 <= total time < 2.0
             number = 1
             for i in range(1, 10):
                 number *= 10
                 if timer.timeit(number) >= 0.2:
                     break
         
         best = min(timer.repeat(repeat, number)) / number
 
         if best > 0.0:
             order = min(-int(math.floor(math.log10(best)) // 3), 3)
         else:
             order = 3
         print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
                                                           precision,
                                                           best * scaling[order],
                                                           units[order])
         if tc > tc_min:
             print "Compiler time: %.2f s" % tc
 
     @testdec.skip_doctest
     def magic_time(self,parameter_s = ''):
         """Time execution of a Python statement or expression.
 
         The CPU and wall clock times are printed, and the value of the
         expression (if any) is returned.  Note that under Win32, system time
         is always reported as 0, since it can not be measured.
 
         This function provides very basic timing functionality.  In Python
         2.3, the timeit module offers more control and sophistication, so this
         could be rewritten to use it (patches welcome).
         
         Some examples:
 
           In [1]: time 2**128
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
           Out[1]: 340282366920938463463374607431768211456L
 
           In [2]: n = 1000000
 
           In [3]: time sum(range(n))
           CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
           Wall time: 1.37
           Out[3]: 499999500000L
 
           In [4]: time print 'hello world'
           hello world
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
 
           Note that the time needed by Python to compile the given expression
           will be reported if it is more than 0.1s.  In this example, the
           actual exponentiation is done by Python at compilation time, so while
           the expression can take a noticeable amount of time to compute, that
           time is purely due to the compilation:
 
           In [5]: time 3**9999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
 
           In [6]: time 3**999999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
           Compiler : 0.78 s
           """
         
         # fail immediately if the given expression can't be compiled
         
         expr = self.shell.prefilter(parameter_s,False)
 
         # Minimum time above which compilation time will be reported
         tc_min = 0.1
         
         try:
             mode = 'eval'
             t0 = clock()
             code = compile(expr,'<timed eval>',mode)
             tc = clock()-t0
         except SyntaxError:
             mode = 'exec'
             t0 = clock()
             code = compile(expr,'<timed exec>',mode)
             tc = clock()-t0
         # skew measurement as little as possible
         glob = self.shell.user_ns
         clk = clock2
         wtime = time.time
         # time execution
         wall_st = wtime()
         if mode=='eval':
             st = clk()
             out = eval(code,glob)
             end = clk()
         else:
             st = clk()
             exec code in glob
             end = clk()
             out = None
         wall_end = wtime()
         # Compute actual times and report
         wall_time = wall_end-wall_st
         cpu_user = end[0]-st[0]
         cpu_sys = end[1]-st[1]
         cpu_tot = cpu_user+cpu_sys
         print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
               (cpu_user,cpu_sys,cpu_tot)
         print "Wall time: %.2f s" % wall_time
         if tc > tc_min:
             print "Compiler : %.2f s" % tc
         return out
 
     @testdec.skip_doctest
     def magic_macro(self,parameter_s = ''):
         """Define a set of input lines as a macro for future re-execution.
 
         Usage:\\
           %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         This will define a global variable called `name` which is a string
         made of joining the slices and lines you specify (n1,n2,... numbers
         above) from your input history into a single string. This variable
         acts like an automatic function which re-executes those lines as if
         you had typed them. You just type 'name' at the prompt and the code
         executes.
 
         The notation for indicating number ranges is: n1-n2 means 'use line
         numbers n1,...n2' (the endpoint is included).  That is, '5-7' means
         using the lines numbered 5,6 and 7.
 
         Note: as a 'hidden' feature, you can also use traditional python slice
         notation, where N:M means numbers N through M-1.
 
         For example, if your history contains (%hist prints it):
         
           44: x=1
           45: y=3
           46: z=x+y
           47: print x
           48: a=5
           49: print 'x',x,'y',y
 
         you can create a macro with lines 44 through 47 (included) and line 49
         called my_macro with:
 
           In [55]: %macro my_macro 44-47 49
 
         Now, typing `my_macro` (without quotes) will re-execute all this code
         in one pass.
 
         You don't need to give the line-numbers in order, and any given line
         number can appear multiple times. You can assemble macros with any
         lines from your input history in any order.
 
         The macro is a simple object which holds its value in an attribute,
         but IPython's display system checks for macros and executes them as
         code instead of printing them when you type their name.
 
         You can view a macro's contents by explicitly printing it with:
         
           'print macro_name'.
 
         For one-off cases which DON'T contain magic function calls in them you
         can obtain similar results by explicitly executing slices from your
         input history with:
 
           In [60]: exec In[44:48]+In[49]"""
 
         opts,args = self.parse_options(parameter_s,'r',mode='list')
         if not args:
             macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
             macs.sort()
             return macs
         if len(args) == 1:
             raise UsageError(
                 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
         name,ranges = args[0], args[1:]
         
         #print 'rng',ranges  # dbg
         lines = self.extract_input_slices(ranges,opts.has_key('r'))
         macro = Macro(lines)
         self.shell.user_ns.update({name:macro})
         print 'Macro `%s` created. To execute, type its name (without quotes).' % name
         print 'Macro contents:'
         print macro,
 
     def magic_save(self,parameter_s = ''):
         """Save a set of lines to a given filename.
 
         Usage:\\
           %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         This function uses the same syntax as %macro for line extraction, but
         instead of creating a macro it saves the resulting string to the
         filename you specify.
 
         It adds a '.py' extension to the file if you don't do so yourself, and
         it asks for confirmation before overwriting existing files."""
 
         opts,args = self.parse_options(parameter_s,'r',mode='list')
         fname,ranges = args[0], args[1:]
         if not fname.endswith('.py'):
             fname += '.py'
         if os.path.isfile(fname):
             ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
             if ans.lower() not in ['y','yes']:
                 print 'Operation cancelled.'
                 return
         cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
         f = file(fname,'w')
         f.write(cmds)
         f.close()
         print 'The following commands were written to file `%s`:' % fname
         print cmds
 
     def _edit_macro(self,mname,macro):
         """open an editor with the macro data in a file"""
         filename = self.shell.mktempfile(macro.value)
         self.shell.hooks.editor(filename)
 
         # and make a new macro object, to replace the old one
         mfile = open(filename)
         mvalue = mfile.read()
         mfile.close()
         self.shell.user_ns[mname] = Macro(mvalue)
 
     def magic_ed(self,parameter_s=''):
         """Alias to %edit."""
         return self.magic_edit(parameter_s)
 
     @testdec.skip_doctest
     def magic_edit(self,parameter_s='',last_call=['','']):
         """Bring up an editor and execute the resulting code.
 
         Usage:
           %edit [options] [args]
 
         %edit runs IPython's editor hook.  The default version of this hook is
         set to call the __IPYTHON__.rc.editor command.  This is read from your
         environment variable $EDITOR.  If this isn't found, it will default to
         vi under Linux/Unix and to notepad under Windows.  See the end of this
         docstring for how to change the editor hook.
 
         You can also set the value of this editor via the command line option
         '-editor' or in your ipythonrc file. This is useful if you wish to use
         specifically for IPython an editor different from your typical default
         (and for Windows users who typically don't set environment variables).
 
         This command allows you to conveniently edit multi-line code right in
         your IPython session.
         
         If called without arguments, %edit opens up an empty editor with a
         temporary file and will execute the contents of this file when you
         close it (don't forget to save it!).
 
 
         Options:
 
         -n <number>: open the editor at a specified line number.  By default,
         the IPython editor hook uses the unix syntax 'editor +N filename', but
         you can configure this by providing your own modified hook if your
         favorite editor supports line-number specifications with a different
         syntax.
         
         -p: this will call the editor with the same data as the previous time
         it was used, regardless of how long ago (in your current session) it
         was.
 
         -r: use 'raw' input.  This option only applies to input taken from the
         user's history.  By default, the 'processed' history is used, so that
         magics are loaded in their transformed version to valid Python.  If
         this option is given, the raw input as typed as the command line is
         used instead.  When you exit the editor, it will be executed by
         IPython's own processor.
         
         -x: do not execute the edited code immediately upon exit. This is
         mainly useful if you are editing programs which need to be called with
         command line arguments, which you can then do using %run.
 
 
         Arguments:
 
         If arguments are given, the following possibilites exist:
 
         - The arguments are numbers or pairs of colon-separated numbers (like
         1 4:8 9). These are interpreted as lines of previous input to be
         loaded into the editor. The syntax is the same of the %macro command.
 
         - If the argument doesn't start with a number, it is evaluated as a
         variable and its contents loaded into the editor. You can thus edit
         any string which contains python code (including the result of
         previous edits).
 
         - If the argument is the name of an object (other than a string),
         IPython will try to locate the file where it was defined and open the
         editor at the point where it is defined. You can use `%edit function`
         to load an editor exactly at the point where 'function' is defined,
         edit it and have the file be executed automatically.
 
         If the object is a macro (see %macro for details), this opens up your
         specified editor with a temporary file containing the macro's data.
         Upon exit, the macro is reloaded with the contents of the file.
 
         Note: opening at an exact line is only supported under Unix, and some
         editors (like kedit and gedit up to Gnome 2.8) do not understand the
         '+NUMBER' parameter necessary for this feature. Good editors like
         (X)Emacs, vi, jed, pico and joe all do.
 
         - If the argument is not found as a variable, IPython will look for a
         file with that name (adding .py if necessary) and load it into the
         editor. It will execute its contents with execfile() when you exit,
         loading any code in the file into your interactive namespace.
 
         After executing your code, %edit will return as output the code you
         typed in the editor (except when it was an existing file). This way
         you can reload the code in further invocations of %edit as a variable,
         via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
         the output.
 
         Note that %edit is also available through the alias %ed.
 
         This is an example of creating a simple function inside the editor and
         then modifying it. First, start up the editor:
 
         In [1]: ed
         Editing... done. Executing edited code...
         Out[1]: 'def foo():n    print "foo() was defined in an editing session"n'
 
         We can then call the function foo():
         
         In [2]: foo()
         foo() was defined in an editing session
 
         Now we edit foo.  IPython automatically loads the editor with the
         (temporary) file where foo() was previously defined:
         
         In [3]: ed foo
         Editing... done. Executing edited code...
 
         And if we call foo() again we get the modified version:
         
         In [4]: foo()
         foo() has now been changed!
 
         Here is an example of how to edit a code snippet successive
         times. First we call the editor:
 
         In [5]: ed
         Editing... done. Executing edited code...
         hello
         Out[5]: "print 'hello'n"
 
         Now we call it again with the previous output (stored in _):
 
         In [6]: ed _
         Editing... done. Executing edited code...
         hello world
         Out[6]: "print 'hello world'n"
 
         Now we call it with the output #8 (stored in _8, also as Out[8]):
 
         In [7]: ed _8
         Editing... done. Executing edited code...
         hello again
         Out[7]: "print 'hello again'n"
 
 
         Changing the default editor hook:
 
         If you wish to write your own editor hook, you can put it in a
         configuration file which you load at startup time.  The default hook
         is defined in the IPython.hooks module, and you can use that as a
         starting example for further modifications.  That file also has
         general instructions on how to set a new hook for use once you've
         defined it."""
         
         # FIXME: This function has become a convoluted mess.  It needs a
         # ground-up rewrite with clean, simple logic.
 
         def make_filename(arg):
             "Make a filename from the given args"
             try:
                 filename = get_py_filename(arg)
             except IOError:
                 if args.endswith('.py'):
                     filename = arg
                 else:
                     filename = None
             return filename
 
         # custom exceptions
         class DataIsObject(Exception): pass
 
         opts,args = self.parse_options(parameter_s,'prxn:')
         # Set a few locals from the options for convenience:
         opts_p = opts.has_key('p')
         opts_r = opts.has_key('r')
         
         # Default line number value
         lineno = opts.get('n',None)
 
         if opts_p:
             args = '_%s' % last_call[0]
             if not self.shell.user_ns.has_key(args):
                 args = last_call[1]
             
         # use last_call to remember the state of the previous call, but don't
         # let it be clobbered by successive '-p' calls.
         try:
             last_call[0] = self.shell.outputcache.prompt_count
             if not opts_p:
                 last_call[1] = parameter_s
         except:
             pass
 
         # by default this is done with temp files, except when the given
         # arg is a filename
         use_temp = 1
 
         if re.match(r'\d',args):
             # Mode where user specifies ranges of lines, like in %macro.
             # This means that you can't edit files whose names begin with
             # numbers this way. Tough.
             ranges = args.split()
             data = ''.join(self.extract_input_slices(ranges,opts_r))
         elif args.endswith('.py'):
             filename = make_filename(args)
             data = ''
             use_temp = 0
         elif args:
             try:
                 # Load the parameter given as a variable. If not a string,
                 # process it as an object instead (below)
 
                 #print '*** args',args,'type',type(args)  # dbg
                 data = eval(args,self.shell.user_ns)
                 if not type(data) in StringTypes:
                     raise DataIsObject
 
             except (NameError,SyntaxError):
                 # given argument is not a variable, try as a filename
                 filename = make_filename(args)
                 if filename is None:
                     warn("Argument given (%s) can't be found as a variable "
                          "or as a filename." % args)
                     return
 
                 data = ''
                 use_temp = 0
             except DataIsObject:
 
                 # macros have a special edit function
                 if isinstance(data,Macro):
                     self._edit_macro(args,data)
                     return
                                 
                 # For objects, try to edit the file where they are defined
                 try:
                     filename = inspect.getabsfile(data)
                     if 'fakemodule' in filename.lower() and inspect.isclass(data):                     
                         # class created by %edit? Try to find source
                         # by looking for method definitions instead, the
                         # __module__ in those classes is FakeModule.
                         attrs = [getattr(data, aname) for aname in dir(data)]
                         for attr in attrs:
                             if not inspect.ismethod(attr):
                                 continue
                             filename = inspect.getabsfile(attr)
                             if filename and 'fakemodule' not in filename.lower():
                                 # change the attribute to be the edit target instead
                                 data = attr 
                                 break
                     
                     datafile = 1
                 except TypeError:
                     filename = make_filename(args)
                     datafile = 1
                     warn('Could not find file where `%s` is defined.\n'
                          'Opening a file named `%s`' % (args,filename))
                 # Now, make sure we can actually read the source (if it was in
                 # a temp file it's gone by now).
                 if datafile:
                     try:
                         if lineno is None:
                             lineno = inspect.getsourcelines(data)[1]
                     except IOError:
                         filename = make_filename(args)
                         if filename is None:
                             warn('The file `%s` where `%s` was defined cannot '
                                  'be read.' % (filename,data))
                             return
                 use_temp = 0
         else:
             data = ''
 
         if use_temp:
             filename = self.shell.mktempfile(data)
             print 'IPython will make a temporary file named:',filename
 
         # do actual editing here
         print 'Editing...',
         sys.stdout.flush()
-        self.shell.hooks.editor(filename,lineno)
+        try:
+            self.shell.hooks.editor(filename,lineno)
+        except IPython.ipapi.TryNext:
+            warn('Could not open editor')
+            return
+        
+        # XXX TODO: should this be generalized for all string vars?
+        # For now, this is special-cased to blocks created by cpaste
+        if args.strip() == 'pasted_block':
+            self.shell.user_ns['pasted_block'] = file_read(filename)
+        
         if opts.has_key('x'):  # -x prevents actual execution
             print
         else:
             print 'done. Executing edited code...'
             if opts_r:
                 self.shell.runlines(file_read(filename))
             else:
                 self.shell.safe_execfile(filename,self.shell.user_ns,
                                          self.shell.user_ns)
+        
+                                                     
         if use_temp:
             try:
                 return open(filename).read()
             except IOError,msg:
                 if msg.filename == filename:
                     warn('File not found. Did you forget to save?')
                     return
                 else:
                     self.shell.showtraceback()
 
     def magic_xmode(self,parameter_s = ''):
         """Switch modes for the exception handlers.
 
         Valid modes: Plain, Context and Verbose.
 
         If called without arguments, acts as a toggle."""
 
         def xmode_switch_err(name):
             warn('Error changing %s exception modes.\n%s' %
                  (name,sys.exc_info()[1]))
 
         shell = self.shell
         new_mode = parameter_s.strip().capitalize()
         try:
             shell.InteractiveTB.set_mode(mode=new_mode)
             print 'Exception reporting mode:',shell.InteractiveTB.mode
         except:
             xmode_switch_err('user')
 
         # threaded shells use a special handler in sys.excepthook
         if shell.isthreaded:
             try:
                 shell.sys_excepthook.set_mode(mode=new_mode)
             except:
                 xmode_switch_err('threaded')
             
     def magic_colors(self,parameter_s = ''):
         """Switch color scheme for prompts, info system and exception handlers.
 
         Currently implemented schemes: NoColor, Linux, LightBG.
 
         Color scheme names are not case-sensitive."""
 
         def color_switch_err(name):
             warn('Error changing %s color schemes.\n%s' %
                  (name,sys.exc_info()[1]))
             
         
         new_scheme = parameter_s.strip()
         if not new_scheme:
             raise UsageError(
                 "%colors: you must specify a color scheme. See '%colors?'")
             return
         # local shortcut
         shell = self.shell
 
         import IPython.rlineimpl as readline
 
         if not readline.have_readline and sys.platform == "win32":
             msg = """\
 Proper color support under MS Windows requires the pyreadline library.
 You can find it at:
 http://ipython.scipy.org/moin/PyReadline/Intro
 Gary's readline needs the ctypes module, from:
 http://starship.python.net/crew/theller/ctypes
 (Note that ctypes is already part of Python versions 2.5 and newer).
 
 Defaulting color scheme to 'NoColor'"""
             new_scheme = 'NoColor'
             warn(msg)
         
         # readline option is 0
         if not shell.has_readline:
             new_scheme = 'NoColor'
             
         # Set prompt colors
         try:
             shell.outputcache.set_colors(new_scheme)
         except:
             color_switch_err('prompt')
         else:
             shell.rc.colors = \
                        shell.outputcache.color_table.active_scheme_name
         # Set exception colors
         try:
             shell.InteractiveTB.set_colors(scheme = new_scheme)
             shell.SyntaxTB.set_colors(scheme = new_scheme)
         except:
             color_switch_err('exception')
 
         # threaded shells use a verbose traceback in sys.excepthook
         if shell.isthreaded:
             try:
                 shell.sys_excepthook.set_colors(scheme=new_scheme)
             except:
                 color_switch_err('system exception handler')
         
         # Set info (for 'object?') colors
         if shell.rc.color_info:
             try:
                 shell.inspector.set_active_scheme(new_scheme)
             except:
                 color_switch_err('object inspector')
         else:
             shell.inspector.set_active_scheme('NoColor')
                 
     def magic_color_info(self,parameter_s = ''):
         """Toggle color_info.
 
         The color_info configuration parameter controls whether colors are
         used for displaying object details (by things like %psource, %pfile or
         the '?' system). This function toggles this value with each call.
 
         Note that unless you have a fairly recent pager (less works better
         than more) in your system, using colored object information displays
         will not work properly. Test it and see."""
         
         self.shell.rc.color_info = 1 - self.shell.rc.color_info
         self.magic_colors(self.shell.rc.colors)
         print 'Object introspection functions have now coloring:',
         print ['OFF','ON'][self.shell.rc.color_info]
 
     def magic_Pprint(self, parameter_s=''):
         """Toggle pretty printing on/off."""
         
         self.shell.rc.pprint = 1 - self.shell.rc.pprint
         print 'Pretty printing has been turned', \
               ['OFF','ON'][self.shell.rc.pprint]
         
     def magic_exit(self, parameter_s=''):
         """Exit IPython, confirming if configured to do so.
 
         You can configure whether IPython asks for confirmation upon exit by
         setting the confirm_exit flag in the ipythonrc file."""
 
         self.shell.exit()
 
     def magic_quit(self, parameter_s=''):
         """Exit IPython, confirming if configured to do so (like %exit)"""
 
         self.shell.exit()
         
     def magic_Exit(self, parameter_s=''):
         """Exit IPython without confirmation."""
 
         self.shell.ask_exit()
 
     #......................................................................
     # Functions to implement unix shell-type things
 
     @testdec.skip_doctest
     def magic_alias(self, parameter_s = ''):
         """Define an alias for a system command.
 
         '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
         Then, typing 'alias_name params' will execute the system command 'cmd
         params' (from your underlying operating system).
 
         Aliases have lower precedence than magic functions and Python normal
         variables, so if 'foo' is both a Python variable and an alias, the
         alias can not be executed until 'del foo' removes the Python variable.
 
         You can use the %l specifier in an alias definition to represent the
         whole line when the alias is called.  For example:
 
           In [2]: alias all echo "Input in brackets: <%l>"
           In [3]: all hello world
           Input in brackets: <hello world>
 
         You can also define aliases with parameters using %s specifiers (one
         per parameter):
         
           In [1]: alias parts echo first %s second %s
           In [2]: %parts A B
           first A second B
           In [3]: %parts A
           Incorrect number of arguments: 2 expected.
           parts is an alias to: 'echo first %s second %s'
 
         Note that %l and %s are mutually exclusive.  You can only use one or
         the other in your aliases.
 
         Aliases expand Python variables just like system calls using ! or !! 
         do: all expressions prefixed with '$' get expanded.  For details of
         the semantic rules, see PEP-215:
         http://www.python.org/peps/pep-0215.html.  This is the library used by
         IPython for variable expansion.  If you want to access a true shell
         variable, an extra $ is necessary to prevent its expansion by IPython:
 
         In [6]: alias show echo
         In [7]: PATH='A Python string'
         In [8]: show $PATH
         A Python string
         In [9]: show $$PATH
         /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
 
         You can use the alias facility to acess all of $PATH.  See the %rehash
         and %rehashx functions, which automatically create aliases for the
         contents of your $PATH.
 
         If called with no parameters, %alias prints the current alias table."""
 
         par = parameter_s.strip()
         if not par:
             stored = self.db.get('stored_aliases', {} )
             atab = self.shell.alias_table
             aliases = atab.keys()
             aliases.sort()
             res = []
             showlast = []
             for alias in aliases:
                 special = False
                 try:
                     tgt = atab[alias][1]
                 except (TypeError, AttributeError):
                     # unsubscriptable? probably a callable
                     tgt = atab[alias]
                     special = True
                 # 'interesting' aliases
                 if (alias in stored or
                     special or 
                     alias.lower() != os.path.splitext(tgt)[0].lower() or
                     ' ' in tgt):
                     showlast.append((alias, tgt))
                 else:
                     res.append((alias, tgt ))                
             
             # show most interesting aliases last
             res.extend(showlast)
             print "Total number of aliases:",len(aliases)
             return res
         try:
             alias,cmd = par.split(None,1)
         except:
             print OInspect.getdoc(self.magic_alias)
         else:
             nargs = cmd.count('%s')
             if nargs>0 and cmd.find('%l')>=0:
                 error('The %s and %l specifiers are mutually exclusive '
                       'in alias definitions.')
             else:  # all looks OK
                 self.shell.alias_table[alias] = (nargs,cmd)
                 self.shell.alias_table_validate(verbose=0)
     # end magic_alias
 
     def magic_unalias(self, parameter_s = ''):
         """Remove an alias"""
 
         aname = parameter_s.strip()
         if aname in self.shell.alias_table:
             del self.shell.alias_table[aname]
         stored = self.db.get('stored_aliases', {} )
         if aname in stored:
             print "Removing %stored alias",aname
             del stored[aname]
             self.db['stored_aliases'] = stored
             
 
     def magic_rehashx(self, parameter_s = ''):
         """Update the alias table with all executable files in $PATH.
 
         This version explicitly checks that every entry in $PATH is a file
         with execute access (os.X_OK), so it is much slower than %rehash.
 
         Under Windows, it checks executability as a match agains a
         '|'-separated string of extensions, stored in the IPython config
         variable win_exec_ext.  This defaults to 'exe|com|bat'.
         
         This function also resets the root module cache of module completer,
         used on slow filesystems.
         """
         
         
         ip = self.api
 
         # for the benefit of module completer in ipy_completers.py
         del ip.db['rootmodules']
         
         path = [os.path.abspath(os.path.expanduser(p)) for p in 
             os.environ.get('PATH','').split(os.pathsep)]
         path = filter(os.path.isdir,path)
         
         alias_table = self.shell.alias_table
         syscmdlist = []
         if os.name == 'posix':
             isexec = lambda fname:os.path.isfile(fname) and \
                      os.access(fname,os.X_OK)
         else:
 
             try:
                 winext = os.environ['pathext'].replace(';','|').replace('.','')
             except KeyError:
                 winext = 'exe|com|bat|py'
             if 'py' not in winext:
                 winext += '|py'
             execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
             isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
         savedir = os.getcwd()
         try:
             # write the whole loop for posix/Windows so we don't have an if in
             # the innermost part
             if os.name == 'posix':
                 for pdir in path:
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         if isexec(ff) and ff not in self.shell.no_alias:
                             # each entry in the alias table must be (N,name),
                             # where N is the number of positional arguments of the
-                            # alias.
-                            alias_table[ff] = (0,ff)
+                            # alias.                            
+                            # Dots will be removed from alias names, since ipython
+                            # assumes names with dots to be python code
+                            alias_table[ff.replace('.','')] = (0,ff)
                             syscmdlist.append(ff)
             else:
                 for pdir in path:
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         base, ext = os.path.splitext(ff)
                         if isexec(ff) and base.lower() not in self.shell.no_alias:
                             if ext.lower() == '.exe':
                                 ff = base
-                            alias_table[base.lower()] = (0,ff)
+                            alias_table[base.lower().replace('.','')] = (0,ff)
                             syscmdlist.append(ff)
             # Make sure the alias table doesn't contain keywords or builtins
             self.shell.alias_table_validate()
             # Call again init_auto_alias() so we get 'rm -i' and other
             # modified aliases since %rehashx will probably clobber them
             
             # no, we don't want them. if %rehashx clobbers them, good,
             # we'll probably get better versions
             # self.shell.init_auto_alias()
             db = ip.db
             db['syscmdlist'] = syscmdlist
         finally:
             os.chdir(savedir)
         
     def magic_pwd(self, parameter_s = ''):
         """Return the current working directory path."""
         return os.getcwd()
 
     def magic_cd(self, parameter_s=''):
         """Change the current working directory.
 
         This command automatically maintains an internal list of directories
         you visit during your IPython session, in the variable _dh. The
         command %dhist shows this history nicely formatted. You can also
         do 'cd -<tab>' to see directory history conveniently.
 
         Usage:
 
           cd 'dir': changes to directory 'dir'.
 
           cd -: changes to the last visited directory.
 
           cd -<n>: changes to the n-th directory in the directory history.
 
           cd --foo: change to directory that matches 'foo' in history
             
           cd -b <bookmark_name>: jump to a bookmark set by %bookmark
              (note: cd <bookmark_name> is enough if there is no
               directory <bookmark_name>, but a bookmark with the name exists.)
               'cd -b <tab>' allows you to tab-complete bookmark names. 
 
         Options:
 
         -q: quiet.  Do not print the working directory after the cd command is
         executed.  By default IPython's cd command does print this directory,
         since the default prompts do not display path information.
         
         Note that !cd doesn't work for this purpose because the shell where
         !command runs is immediately discarded after executing 'command'."""
 
         parameter_s = parameter_s.strip()
         #bkms = self.shell.persist.get("bookmarks",{})
 
         oldcwd = os.getcwd()
         numcd = re.match(r'(-)(\d+)$',parameter_s)
         # jump in directory history by number
         if numcd:
             nn = int(numcd.group(2))
             try:
                 ps = self.shell.user_ns['_dh'][nn]
             except IndexError:
                 print 'The requested directory does not exist in history.'
                 return
             else:
                 opts = {}
         elif parameter_s.startswith('--'):
             ps = None
             fallback = None
             pat = parameter_s[2:]
             dh = self.shell.user_ns['_dh']
             # first search only by basename (last component)
             for ent in reversed(dh):
                 if pat in os.path.basename(ent) and os.path.isdir(ent):
                     ps = ent
                     break
             
                 if fallback is None and pat in ent and os.path.isdir(ent):
                     fallback = ent
                 
             # if we have no last part match, pick the first full path match
             if ps is None:
                 ps = fallback
             
             if ps is None:
                 print "No matching entry in directory history"
                 return
             else:
                 opts = {}
                 
             
         else:
             #turn all non-space-escaping backslashes to slashes, 
             # for c:\windows\directory\names\
             parameter_s = re.sub(r'\\(?! )','/', parameter_s)            
             opts,ps = self.parse_options(parameter_s,'qb',mode='string')
         # jump to previous
         if ps == '-':
             try:
                 ps = self.shell.user_ns['_dh'][-2]
             except IndexError:
                 raise UsageError('%cd -: No previous directory to change to.')
         # jump to bookmark if needed
         else:
             if not os.path.isdir(ps) or opts.has_key('b'):
                 bkms = self.db.get('bookmarks', {})
             
                 if bkms.has_key(ps):
                     target = bkms[ps]
                     print '(bookmark:%s) -> %s' % (ps,target)
                     ps = target
                 else:
                     if opts.has_key('b'):
                         raise UsageError("Bookmark '%s' not found.  "
                               "Use '%%bookmark -l' to see your bookmarks." % ps)
             
         # at this point ps should point to the target dir
         if ps:
             try:                
                 os.chdir(os.path.expanduser(ps))
                 if self.shell.rc.term_title:
                     #print 'set term title:',self.shell.rc.term_title  # dbg
                     platutils.set_term_title('IPy ' + abbrev_cwd())
             except OSError:
                 print sys.exc_info()[1]
             else:
                 cwd = os.getcwd()
                 dhist = self.shell.user_ns['_dh']
                 if oldcwd != cwd:
                     dhist.append(cwd)
                     self.db['dhist'] = compress_dhist(dhist)[-100:]
                 
         else:
             os.chdir(self.shell.home_dir)
             if self.shell.rc.term_title:
                 platutils.set_term_title("IPy ~")
             cwd = os.getcwd()
             dhist = self.shell.user_ns['_dh']
             
             if oldcwd != cwd:
                 dhist.append(cwd)
                 self.db['dhist'] = compress_dhist(dhist)[-100:]
         if not 'q' in opts and self.shell.user_ns['_dh']:
             print self.shell.user_ns['_dh'][-1]
 
 
     def magic_env(self, parameter_s=''):
         """List environment variables."""
         
         return os.environ.data
 
     def magic_pushd(self, parameter_s=''):
         """Place the current dir on stack and change directory.
         
         Usage:\\
           %pushd ['dirname']
         """
         
         dir_s = self.shell.dir_stack
         tgt = os.path.expanduser(parameter_s)
         cwd = os.getcwd().replace(self.home_dir,'~')
         if tgt:
             self.magic_cd(parameter_s)
         dir_s.insert(0,cwd)
         return self.magic_dirs()
 
     def magic_popd(self, parameter_s=''):
         """Change to directory popped off the top of the stack.
         """
         if not self.shell.dir_stack:
             raise UsageError("%popd on empty stack")
         top = self.shell.dir_stack.pop(0)
         self.magic_cd(top)
         print "popd ->",top
 
     def magic_dirs(self, parameter_s=''):
         """Return the current directory stack."""
 
         return self.shell.dir_stack
 
     def magic_dhist(self, parameter_s=''):
         """Print your history of visited directories.
 
         %dhist       -> print full history\\
         %dhist n     -> print last n entries only\\
         %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
 
         This history is automatically maintained by the %cd command, and
         always available as the global list variable _dh. You can use %cd -<n>
         to go to directory number <n>.
         
         Note that most of time, you should view directory history by entering
         cd -<TAB>.
         
         """
 
         dh = self.shell.user_ns['_dh']
         if parameter_s:
             try:
                 args = map(int,parameter_s.split())
             except:
                 self.arg_err(Magic.magic_dhist)
                 return
             if len(args) == 1:
                 ini,fin = max(len(dh)-(args[0]),0),len(dh)
             elif len(args) == 2:
                 ini,fin = args
             else:
                 self.arg_err(Magic.magic_dhist)
                 return
         else:
             ini,fin = 0,len(dh)
         nlprint(dh,
                 header = 'Directory history (kept in _dh)',
                 start=ini,stop=fin)
 
     @testdec.skip_doctest
     def magic_sc(self, parameter_s=''):
         """Shell capture - execute a shell command and capture its output.
 
         DEPRECATED. Suboptimal, retained for backwards compatibility.
         
         You should use the form 'var = !command' instead. Example:
          
          "%sc -l myfiles = ls ~" should now be written as
             
          "myfiles = !ls ~"
          
         myfiles.s, myfiles.l and myfiles.n still apply as documented
         below.
 
         --
         %sc [options] varname=command
 
         IPython will run the given command using commands.getoutput(), and
         will then update the user's interactive namespace with a variable
         called varname, containing the value of the call.  Your command can
         contain shell wildcards, pipes, etc.
 
         The '=' sign in the syntax is mandatory, and the variable name you
         supply must follow Python's standard conventions for valid names.
         
         (A special format without variable name exists for internal use)
 
         Options:
 
           -l: list output.  Split the output on newlines into a list before
           assigning it to the given variable.  By default the output is stored
           as a single string.
 
           -v: verbose.  Print the contents of the variable.
 
         In most cases you should not need to split as a list, because the
         returned value is a special type of string which can automatically
         provide its contents either as a list (split on newlines) or as a
         space-separated string.  These are convenient, respectively, either
         for sequential processing or to be passed to a shell command.
 
         For example:
 
         # all-random
         
             # Capture into variable a
             In [1]: sc a=ls *py
 
             # a is a string with embedded newlines
             In [2]: a
             Out[2]: 'setup.py\\nwin32_manual_post_install.py'
 
             # which can be seen as a list:
             In [3]: a.l
             Out[3]: ['setup.py', 'win32_manual_post_install.py']
 
             # or as a whitespace-separated string:
             In [4]: a.s
             Out[4]: 'setup.py win32_manual_post_install.py'
 
             # a.s is useful to pass as a single command line:
             In [5]: !wc -l $a.s
               146 setup.py
               130 win32_manual_post_install.py
               276 total
 
             # while the list form is useful to loop over:
             In [6]: for f in a.l:
               ...:      !wc -l $f
               ...:
             146 setup.py
             130 win32_manual_post_install.py
 
         Similiarly, the lists returned by the -l option are also special, in
         the sense that you can equally invoke the .s attribute on them to
         automatically get a whitespace-separated string from their contents:
 
             In [7]: sc -l b=ls *py
 
             In [8]: b
             Out[8]: ['setup.py', 'win32_manual_post_install.py']
 
             In [9]: b.s
             Out[9]: 'setup.py win32_manual_post_install.py'
 
         In summary, both the lists and strings used for ouptut capture have
         the following special attributes:
 
             .l (or .list) : value as list.
             .n (or .nlstr): value as newline-separated string.
             .s (or .spstr): value as space-separated string.
         """
 
         opts,args = self.parse_options(parameter_s,'lv')
         # Try to get a variable name and command to run
         try:
             # the variable name must be obtained from the parse_options
             # output, which uses shlex.split to strip options out.
             var,_ = args.split('=',1)
             var = var.strip()
             # But the the command has to be extracted from the original input
             # parameter_s, not on what parse_options returns, to avoid the
             # quote stripping which shlex.split performs on it.
             _,cmd = parameter_s.split('=',1)
         except ValueError:
             var,cmd = '',''
         # If all looks ok, proceed
         out,err = self.shell.getoutputerror(cmd)
         if err:
             print >> Term.cerr,err
         if opts.has_key('l'):
             out = SList(out.split('\n'))
         else:
             out = LSString(out)
         if opts.has_key('v'):
             print '%s ==\n%s' % (var,pformat(out))
         if var:
             self.shell.user_ns.update({var:out})
         else:
             return out
 
     def magic_sx(self, parameter_s=''):
         """Shell execute - run a shell command and capture its output.
 
         %sx command
 
         IPython will run the given command using commands.getoutput(), and
         return the result formatted as a list (split on '\\n').  Since the
         output is _returned_, it will be stored in ipython's regular output
         cache Out[N] and in the '_N' automatic variables.
 
         Notes:
 
         1) If an input line begins with '!!', then %sx is automatically
         invoked.  That is, while:
           !ls
         causes ipython to simply issue system('ls'), typing
           !!ls
         is a shorthand equivalent to:
           %sx ls
         
         2) %sx differs from %sc in that %sx automatically splits into a list,
         like '%sc -l'.  The reason for this is to make it as easy as possible
         to process line-oriented shell output via further python commands.
         %sc is meant to provide much finer control, but requires more
         typing.
 
         3) Just like %sc -l, this is a list with special attributes:
 
           .l (or .list) : value as list.
           .n (or .nlstr): value as newline-separated string.
           .s (or .spstr): value as whitespace-separated string.
 
         This is very useful when trying to use such lists as arguments to
         system commands."""
 
         if parameter_s:
             out,err = self.shell.getoutputerror(parameter_s)
             if err:
                 print >> Term.cerr,err
             return SList(out.split('\n'))
 
     def magic_bg(self, parameter_s=''):
         """Run a job in the background, in a separate thread.
 
         For example,
 
           %bg myfunc(x,y,z=1)
 
         will execute 'myfunc(x,y,z=1)' in a background thread.  As soon as the
         execution starts, a message will be printed indicating the job
         number.  If your job number is 5, you can use
 
           myvar = jobs.result(5)  or  myvar = jobs[5].result
 
         to assign this result to variable 'myvar'.
 
         IPython has a job manager, accessible via the 'jobs' object.  You can
         type jobs? to get more information about it, and use jobs.<TAB> to see
         its attributes.  All attributes not starting with an underscore are
         meant for public use.
 
         In particular, look at the jobs.new() method, which is used to create
         new jobs.  This magic %bg function is just a convenience wrapper
         around jobs.new(), for expression-based jobs.  If you want to create a
         new job with an explicit function object and arguments, you must call
         jobs.new() directly.
 
         The jobs.new docstring also describes in detail several important
         caveats associated with a thread-based model for background job
         execution.  Type jobs.new? for details.
 
         You can check the status of all jobs with jobs.status().
 
         The jobs variable is set by IPython into the Python builtin namespace.
         If you ever declare a variable named 'jobs', you will shadow this
         name.  You can either delete your global jobs variable to regain
         access to the job manager, or make a new name and assign it manually
         to the manager (stored in IPython's namespace).  For example, to
         assign the job manager to the Jobs name, use:
 
           Jobs = __builtins__.jobs"""
         
         self.shell.jobs.new(parameter_s,self.shell.user_ns)
         
     def magic_r(self, parameter_s=''):
         """Repeat previous input.
 
         Note: Consider using the more powerfull %rep instead!
         
         If given an argument, repeats the previous command which starts with
         the same string, otherwise it just repeats the previous input.
 
         Shell escaped commands (with ! as first character) are not recognized
         by this system, only pure python code and magic commands.
         """
 
         start = parameter_s.strip()
         esc_magic = self.shell.ESC_MAGIC
         # Identify magic commands even if automagic is on (which means
         # the in-memory version is different from that typed by the user).
         if self.shell.rc.automagic:
             start_magic = esc_magic+start
         else:
             start_magic = start
         # Look through the input history in reverse
         for n in range(len(self.shell.input_hist)-2,0,-1):
             input = self.shell.input_hist[n]
             # skip plain 'r' lines so we don't recurse to infinity
             if input != '_ip.magic("r")\n' and \
                    (input.startswith(start) or input.startswith(start_magic)):
                 #print 'match',`input`  # dbg
                 print 'Executing:',input,
                 self.shell.runlines(input)
                 return
         print 'No previous input matching `%s` found.' % start
 
     
     def magic_bookmark(self, parameter_s=''):
         """Manage IPython's bookmark system.
 
         %bookmark <name>       - set bookmark to current dir
         %bookmark <name> <dir> - set bookmark to <dir>
         %bookmark -l           - list all bookmarks
         %bookmark -d <name>    - remove bookmark
         %bookmark -r           - remove all bookmarks
 
         You can later on access a bookmarked folder with:
           %cd -b <name>
         or simply '%cd <name>' if there is no directory called <name> AND
         there is such a bookmark defined.
 
         Your bookmarks persist through IPython sessions, but they are
         associated with each profile."""
 
         opts,args = self.parse_options(parameter_s,'drl',mode='list')
         if len(args) > 2:
             raise UsageError("%bookmark: too many arguments")
 
         bkms = self.db.get('bookmarks',{})
             
         if opts.has_key('d'):
             try:
                 todel = args[0]
             except IndexError:
                 raise UsageError(
                     "%bookmark -d: must provide a bookmark to delete")
             else:
                 try:
                     del bkms[todel]
                 except KeyError:
                     raise UsageError(
                         "%%bookmark -d: Can't delete bookmark '%s'" % todel)
 
         elif opts.has_key('r'):
             bkms = {}
         elif opts.has_key('l'):
             bks = bkms.keys()
             bks.sort()
             if bks:
                 size = max(map(len,bks))
             else:
                 size = 0
             fmt = '%-'+str(size)+'s -> %s'
             print 'Current bookmarks:'
             for bk in bks:
                 print fmt % (bk,bkms[bk])
         else:
             if not args:
                 raise UsageError("%bookmark: You must specify the bookmark name")
             elif len(args)==1:
                 bkms[args[0]] = os.getcwd()
             elif len(args)==2:
                 bkms[args[0]] = args[1]
         self.db['bookmarks'] = bkms
 
     def magic_pycat(self, parameter_s=''):
         """Show a syntax-highlighted file through a pager.
 
         This magic is similar to the cat utility, but it will assume the file
         to be Python source and will show it with syntax highlighting. """
         
         try:
             filename = get_py_filename(parameter_s)
             cont = file_read(filename)
         except IOError:
             try:
                 cont = eval(parameter_s,self.user_ns)
             except NameError:
                 cont = None
         if cont is None:
             print "Error: no such file or variable"
             return
             
         page(self.shell.pycolorize(cont),
              screen_lines=self.shell.rc.screen_length)
 
     def magic_cpaste(self, parameter_s=''):
         """Allows you to paste & execute a pre-formatted code block from clipboard.
         
         You must terminate the block with '--' (two minus-signs) alone on the
         line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
         is the new sentinel for this operation)
         
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
         ignored, to allow pasting directly from e-mails, diff files and
         doctests (the '...' continuation prompt is also stripped).  The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
         
         You can also pass a variable name as an argument, e.g. '%cpaste foo'.
         This assigns the pasted block to variable 'foo' as string, without 
         dedenting or executing it (preceding >>> and + is still stripped)
         
+        '%cpaste -r' re-executes the block previously entered by cpaste.
+        
         Do not be alarmed by garbled output on Windows (it's a readline bug). 
         Just press enter and type -- (and press enter again) and the block 
         will be what was just pasted.
         
         IPython statements (magics, shell escapes) are not supported (yet).
         """
-        opts,args = self.parse_options(parameter_s,'s:',mode='string')
+        opts,args = self.parse_options(parameter_s,'rs:',mode='string')
         par = args.strip()
+        if opts.has_key('r'):
+            b = self.user_ns.get('pasted_block', None)
+            if b is None:
+                raise UsageError('No previous pasted block available')
+            print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
+            exec b in self.user_ns
+            return
+        
         sentinel = opts.get('s','--')
 
         # Regular expressions that declare text we strip from the input:
         strip_re =  [r'^\s*In \[\d+\]:', # IPython input prompt
                      r'^\s*(\s?>)+', # Python input prompt
                      r'^\s*\.{3,}', # Continuation prompts
                      r'^\++',
                      ]
 
         strip_from_start = map(re.compile,strip_re)
         
         from IPython import iplib
         lines = []
         print "Pasting code; enter '%s' alone on the line to stop." % sentinel
         while 1:
             l = iplib.raw_input_original(':')
             if l ==sentinel:
                 break
             
             for pat in strip_from_start: 
                 l = pat.sub('',l)
             lines.append(l)
                          
         block = "\n".join(lines) + '\n'
         #print "block:\n",block
         if not par:
             b = textwrap.dedent(block)
-            exec b in self.user_ns            
             self.user_ns['pasted_block'] = b
+            exec b in self.user_ns
         else:
             self.user_ns[par] = SList(block.splitlines())
             print "Block assigned to '%s'" % par
             
     def magic_quickref(self,arg):
         """ Show a quick reference sheet """
         import IPython.usage
         qr = IPython.usage.quick_reference + self.magic_magic('-brief')
         
         page(qr)
         
     def magic_upgrade(self,arg):
         """ Upgrade your IPython installation
         
         This will copy the config files that don't yet exist in your 
         ipython dir from the system config dir. Use this after upgrading 
         IPython if you don't wish to delete your .ipython dir.
 
         Call with -nolegacy to get rid of ipythonrc* files (recommended for
         new users)
 
         """
         ip = self.getapi()
         ipinstallation = path(IPython.__file__).dirname()
         upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
         src_config = ipinstallation / 'UserConfig'
         userdir = path(ip.options.ipythondir)
         cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
         print ">",cmd
         shell(cmd)
         if arg == '-nolegacy':
             legacy = userdir.files('ipythonrc*')
             print "Nuking legacy files:",legacy
             
             [p.remove() for p in legacy]
             suffix = (sys.platform == 'win32' and '.ini' or '')
             (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
 
 
     def magic_doctest_mode(self,parameter_s=''):
         """Toggle doctest mode on and off.
 
         This mode allows you to toggle the prompt behavior between normal
         IPython prompts and ones that are as similar to the default IPython
         interpreter as possible.
 
         It also supports the pasting of code snippets that have leading '>>>'
         and '...' prompts in them.  This means that you can paste doctests from
         files or docstrings (even if they have leading whitespace), and the
         code will execute correctly.  You can then use '%history -tn' to see
         the translated history without line numbers; this will give you the
         input after removal of all the leading prompts and whitespace, which
         can be pasted back into an editor.
 
         With these features, you can switch into this mode easily whenever you
         need to do testing and changes to doctests, without having to leave
         your existing IPython session.
         """
 
         # XXX - Fix this to have cleaner activate/deactivate calls.
         from IPython.Extensions import InterpreterPasteInput as ipaste
         from IPython.ipstruct import Struct
 
         # Shorthands
         shell = self.shell
         oc = shell.outputcache
         rc = shell.rc
         meta = shell.meta
         # dstore is a data store kept in the instance metadata bag to track any
         # changes we make, so we can undo them later.
         dstore = meta.setdefault('doctest_mode',Struct())
         save_dstore = dstore.setdefault
 
         # save a few values we'll need to recover later
         mode = save_dstore('mode',False)
         save_dstore('rc_pprint',rc.pprint)
         save_dstore('xmode',shell.InteractiveTB.mode)
         save_dstore('rc_separate_out',rc.separate_out)
         save_dstore('rc_separate_out2',rc.separate_out2)
         save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
         save_dstore('rc_separate_in',rc.separate_in)
 
         if mode == False:
             # turn on
             ipaste.activate_prefilter()
 
             oc.prompt1.p_template = '>>> '
             oc.prompt2.p_template = '... '
             oc.prompt_out.p_template = ''
 
             # Prompt separators like plain python
             oc.input_sep = oc.prompt1.sep = ''
             oc.output_sep = ''
             oc.output_sep2 = ''
 
             oc.prompt1.pad_left = oc.prompt2.pad_left = \
                                   oc.prompt_out.pad_left = False
 
             rc.pprint = False
 
             shell.magic_xmode('Plain')
 
         else:
             # turn off
             ipaste.deactivate_prefilter()
 
             oc.prompt1.p_template = rc.prompt_in1
             oc.prompt2.p_template = rc.prompt_in2
             oc.prompt_out.p_template = rc.prompt_out
 
             oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
 
             oc.output_sep = dstore.rc_separate_out
             oc.output_sep2 = dstore.rc_separate_out2
 
             oc.prompt1.pad_left = oc.prompt2.pad_left = \
                          oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
 
             rc.pprint = dstore.rc_pprint
 
             shell.magic_xmode(dstore.xmode)
 
         # Store new mode and inform
         dstore.mode = bool(1-int(mode))
         print 'Doctest mode is:',
         print ['OFF','ON'][dstore.mode]
 
 # end Magic

IPython/Release.py

@@ -1,99 +1,121
 # -*- coding: utf-8 -*-
-"""Release data for the IPython project.
-
-$Id: Release.py 3002 2008-02-01 07:17:00Z fperez $"""
+"""Release data for the IPython project."""
 
 #*****************************************************************************
 #       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #       Copyright (c) 2001 Janko Hauser <[e-mail]> and Nathaniel Gray
 #       <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 # Name of the package for release purposes.  This is the name which labels
 # the tarballs and RPMs made by distutils, so it's best to lowercase it.
 name = 'ipython'
 
 # For versions with substrings (like 0.6.16.svn), use an extra . to separate
 # the new substring.  We have to avoid using either dashes or underscores,
 # because bdist_rpm does not accept dashes (an RPM) convention, and
 # bdist_deb does not accept underscores (a Debian convention).
 
 development = False    # change this to False to do a release
-version_base = '0.9.beta'
+version_base = '0.9.1'
 branch = 'ipython'
-revision = '1099'
+revision = '1143'
 
 if development:
     if branch == 'ipython':
         version = '%s.bzr.r%s' % (version_base, revision)
     else:
         version = '%s.bzr.r%s.%s' % (version_base, revision, branch)
 else:
     version = version_base
 
 
-description = "Tools for interactive development in Python."
+description = "An interactive computing environment for Python"
 
 long_description = \
 """
-IPython provides a replacement for the interactive Python interpreter with
-extra functionality.
+The goal of IPython is to create a comprehensive environment for
+interactive and exploratory computing.  To support this goal, IPython
+has two main components:
+
+* An enhanced interactive Python shell.
+
+* An architecture for interactive parallel computing.
+
+The enhanced interactive Python shell has the following main features:
+
+* Comprehensive object introspection.
+
+* Input history, persistent across sessions.
 
-Main features:
+* Caching of output results during a session with automatically generated
+  references.
 
- * Comprehensive object introspection.
+* Readline based name completion.
 
- * Input history, persistent across sessions.
+* Extensible system of 'magic' commands for controlling the environment and
+  performing many tasks related either to IPython or the operating system.
 
- * Caching of output results during a session with automatically generated
-   references.
+* Configuration system with easy switching between different setups (simpler
+  than changing $PYTHONSTARTUP environment variables every time).
 
- * Readline based name completion.
+* Session logging and reloading.
 
- * Extensible system of 'magic' commands for controlling the environment and
-   performing many tasks related either to IPython or the operating system.
+* Extensible syntax processing for special purpose situations.
 
- * Configuration system with easy switching between different setups (simpler
-   than changing $PYTHONSTARTUP environment variables every time).
+* Access to the system shell with user-extensible alias system.
 
- * Session logging and reloading.
+* Easily embeddable in other Python programs and wxPython GUIs.
 
- * Extensible syntax processing for special purpose situations.
+* Integrated access to the pdb debugger and the Python profiler. 
 
- * Access to the system shell with user-extensible alias system.
+The parallel computing architecture has the following main features:
 
- * Easily embeddable in other Python programs.
+* Quickly parallelize Python code from an interactive Python/IPython session.
 
- * Integrated access to the pdb debugger and the Python profiler. 
+* A flexible and dynamic process model that be deployed on anything from 
+  multicore workstations to supercomputers.
 
- The latest development version is always available at the IPython subversion
- repository_.
+* An architecture that supports many different styles of parallelism, from
+  message passing to task farming.
 
-.. _repository: http://ipython.scipy.org/svn/ipython/ipython/trunk#egg=ipython-dev
- """
+* Both blocking and fully asynchronous interfaces.
+
+* High level APIs that enable many things to be parallelized in a few lines
+  of code.
+
+* Share live parallel jobs with other users securely.  
+
+* Dynamically load balanced task farming system.
+
+* Robust error handling in parallel code.
+
+The latest development version is always available from IPython's `Launchpad 
+site <http://launchpad.net/ipython>`_.
+"""
 
 license = 'BSD'
 
 authors = {'Fernando' : ('Fernando Perez','[e-mail]'),
            'Janko'    : ('Janko Hauser','[e-mail]'),
            'Nathan'   : ('Nathaniel Gray','[e-mail]'),
            'Ville'    : ('Ville Vainio','[e-mail]'),
            'Brian'    : ('Brian E Granger', '[e-mail]'),
            'Min'      : ('Min Ragan-Kelley', '[e-mail]')
            }
 
 author = 'The IPython Development Team'
 
 author_email = '[e-mail]'
 
 url = 'http://ipython.scipy.org'
 
 download_url = 'http://ipython.scipy.org/dist'
 
 platforms = ['Linux','Mac OSX','Windows XP/2000/NT','Windows 95/98/ME']
 
 keywords = ['Interactive','Interpreter','Shell','Parallel','Distributed']

IPython/Shell.py

@@ -1,1236 +1,1249
 # -*- coding: utf-8 -*-
 """IPython Shell classes.
 
 All the matplotlib support code was co-developed with John Hunter,
 matplotlib's author.
 
 $Id: Shell.py 3024 2008-02-07 15:34:42Z darren.dale $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001-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 IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 # Code begins
 # Stdlib imports
 import __builtin__
 import __main__
 import Queue
 import inspect
 import os
 import sys
 import thread
 import threading
 import time
 
 from signal import signal, SIGINT
 
 try:
     import ctypes
     HAS_CTYPES = True
 except ImportError:
     HAS_CTYPES = False
 
 # IPython imports
 import IPython
 from IPython import ultraTB, ipapi
+from IPython.Magic import Magic
 from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
 from IPython.iplib import InteractiveShell
 from IPython.ipmaker import make_IPython
-from IPython.Magic import Magic
 from IPython.ipstruct import Struct
+from IPython.testing import decorators as testdec
 
 # Globals
 # global flag to pass around information about Ctrl-C without exceptions
 KBINT = False
 
 # global flag to turn on/off Tk support.
 USE_TK = False
 
 # ID for the main thread, used for cross-thread exceptions
 MAIN_THREAD_ID = thread.get_ident()
 
 # Tag when runcode() is active, for exception handling
 CODE_RUN = None
 
 # Default timeout for waiting for multithreaded shells (in seconds)
 GUI_TIMEOUT = 10
 
 #-----------------------------------------------------------------------------
 # This class is trivial now, but I want to have it in to publish a clean
 # interface. Later when the internals are reorganized, code that uses this
 # shouldn't have to change.
 
 class IPShell:
     """Create an IPython instance."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=InteractiveShell):
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,shell_class=shell_class)
 
     def mainloop(self,sys_exit=0,banner=None):
         self.IP.mainloop(banner)
         if sys_exit:
             sys.exit()
 
 #-----------------------------------------------------------------------------
 def kill_embedded(self,parameter_s=''):
     """%kill_embedded : deactivate for good the current embedded IPython.
 
     This function (after asking for confirmation) sets an internal flag so that
     an embedded IPython will never activate again.  This is useful to
     permanently disable a shell that is being called inside a loop: once you've
     figured out what you needed from it, you may then kill it and the program
     will then continue to run without the interactive shell interfering again.
     """
     
     kill = ask_yes_no("Are you sure you want to kill this embedded instance "
                      "(y/n)? [y/N] ",'n')
     if kill:
         self.shell.embedded_active = False
         print "This embedded IPython will not reactivate anymore once you exit."
     
 class IPShellEmbed:
     """Allow embedding an IPython shell into a running program.
 
     Instances of this class are callable, with the __call__ method being an
     alias to the embed() method of an InteractiveShell instance.
 
     Usage (see also the example-embed.py file for a running example):
 
     ipshell = IPShellEmbed([argv,banner,exit_msg,rc_override])
 
     - argv: list containing valid command-line options for IPython, as they
     would appear in sys.argv[1:].
 
     For example, the following command-line options:
 
       $ ipython -prompt_in1 'Input <\\#>' -colors LightBG
 
     would be passed in the argv list as:
 
       ['-prompt_in1','Input <\\#>','-colors','LightBG']
 
     - banner: string which gets printed every time the interpreter starts.
 
     - exit_msg: string which gets printed every time the interpreter exits.
 
     - rc_override: a dict or Struct of configuration options such as those
     used by IPython. These options are read from your ~/.ipython/ipythonrc
     file when the Shell object is created. Passing an explicit rc_override
     dict with any options you want allows you to override those values at
     creation time without having to modify the file. This way you can create
     embeddable instances configured in any way you want without editing any
     global files (thus keeping your interactive IPython configuration
     unchanged).
 
     Then the ipshell instance can be called anywhere inside your code:
     
     ipshell(header='') -> Opens up an IPython shell.
 
     - header: string printed by the IPython shell upon startup. This can let
     you know where in your code you are when dropping into the shell. Note
     that 'banner' gets prepended to all calls, so header is used for
     location-specific information.
 
     For more details, see the __call__ method below.
 
     When the IPython shell is exited with Ctrl-D, normal program execution
     resumes.
 
     This functionality was inspired by a posting on comp.lang.python by cmkl
     <[e-mail]> on Dec. 06/01 concerning similar uses of pyrepl, and
     by the IDL stop/continue commands."""
 
     def __init__(self,argv=None,banner='',exit_msg=None,rc_override=None,
                  user_ns=None):
         """Note that argv here is a string, NOT a list."""
         self.set_banner(banner)
         self.set_exit_msg(exit_msg)
         self.set_dummy_mode(0)
 
         # sys.displayhook is a global, we need to save the user's original
         # Don't rely on __displayhook__, as the user may have changed that.
         self.sys_displayhook_ori = sys.displayhook
 
         # save readline completer status
         try:
             #print 'Save completer',sys.ipcompleter  # dbg
             self.sys_ipcompleter_ori = sys.ipcompleter
         except:
             pass # not nested with IPython
         
         self.IP = make_IPython(argv,rc_override=rc_override,
                                embedded=True,
                                user_ns=user_ns)
 
         ip = ipapi.IPApi(self.IP)
         ip.expose_magic("kill_embedded",kill_embedded)
 
         # copy our own displayhook also
         self.sys_displayhook_embed = sys.displayhook
         # and leave the system's display hook clean
         sys.displayhook = self.sys_displayhook_ori
         # don't use the ipython crash handler so that user exceptions aren't
         # trapped
         sys.excepthook = ultraTB.FormattedTB(color_scheme = self.IP.rc.colors,
                                              mode = self.IP.rc.xmode,
                                              call_pdb = self.IP.rc.pdb)
         self.restore_system_completer()
 
     def restore_system_completer(self):
         """Restores the readline completer which was in place.
 
         This allows embedded IPython within IPython not to disrupt the
         parent's completion.
         """
         
         try:
             self.IP.readline.set_completer(self.sys_ipcompleter_ori)
             sys.ipcompleter = self.sys_ipcompleter_ori
         except:
             pass
 
     def __call__(self,header='',local_ns=None,global_ns=None,dummy=None):
         """Activate the interactive interpreter.
 
         __call__(self,header='',local_ns=None,global_ns,dummy=None) -> Start
         the interpreter shell with the given local and global namespaces, and
         optionally print a header string at startup.
 
         The shell can be globally activated/deactivated using the
         set/get_dummy_mode methods. This allows you to turn off a shell used
         for debugging globally.
 
         However, *each* time you call the shell you can override the current
         state of dummy_mode with the optional keyword parameter 'dummy'. For
         example, if you set dummy mode on with IPShell.set_dummy_mode(1), you
         can still have a specific call work by making it as IPShell(dummy=0).
 
         The optional keyword parameter dummy controls whether the call
         actually does anything.  """
 
         # If the user has turned it off, go away
         if not self.IP.embedded_active:
             return
 
         # Normal exits from interactive mode set this flag, so the shell can't
         # re-enter (it checks this variable at the start of interactive mode).
         self.IP.exit_now = False
 
         # Allow the dummy parameter to override the global __dummy_mode
         if dummy or (dummy != 0 and self.__dummy_mode):
             return
 
         # Set global subsystems (display,completions) to our values
         sys.displayhook = self.sys_displayhook_embed
         if self.IP.has_readline:
             self.IP.set_completer()
 
         if self.banner and header:
             format = '%s\n%s\n'
         else:
             format = '%s%s\n'
         banner =  format % (self.banner,header)
 
         # Call the embedding code with a stack depth of 1 so it can skip over
         # our call and get the original caller's namespaces.
         self.IP.embed_mainloop(banner,local_ns,global_ns,stack_depth=1)
 
         if self.exit_msg:
             print self.exit_msg
             
         # Restore global systems (display, completion)
         sys.displayhook = self.sys_displayhook_ori
         self.restore_system_completer()
     
     def set_dummy_mode(self,dummy):
         """Sets the embeddable shell's dummy mode parameter.
 
         set_dummy_mode(dummy): dummy = 0 or 1.
 
         This parameter is persistent and makes calls to the embeddable shell
         silently return without performing any action. This allows you to
         globally activate or deactivate a shell you're using with a single call.
 
         If you need to manually"""
 
         if dummy not in [0,1,False,True]:
             raise ValueError,'dummy parameter must be boolean'
         self.__dummy_mode = dummy
 
     def get_dummy_mode(self):
         """Return the current value of the dummy mode parameter.
         """
         return self.__dummy_mode
     
     def set_banner(self,banner):
         """Sets the global banner.
 
         This banner gets prepended to every header printed when the shell
         instance is called."""
 
         self.banner = banner
 
     def set_exit_msg(self,exit_msg):
         """Sets the global exit_msg.
 
         This exit message gets printed upon exiting every time the embedded
         shell is called. It is None by default. """
 
         self.exit_msg = exit_msg
 
 #-----------------------------------------------------------------------------
 if HAS_CTYPES:
     #  Add async exception support.  Trick taken from:
     # http://sebulba.wikispaces.com/recipe+thread2
     def _async_raise(tid, exctype):
         """raises the exception, performs cleanup if needed"""
         if not inspect.isclass(exctype):
             raise TypeError("Only types can be raised (not instances)")
         res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid,
                                                          ctypes.py_object(exctype))
         if res == 0:
             raise ValueError("invalid thread id")
         elif res != 1:
             # """if it returns a number greater than one, you're in trouble, 
             # and you should call it again with exc=NULL to revert the effect"""
             ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, 0)
             raise SystemError("PyThreadState_SetAsyncExc failed")
 
     def sigint_handler (signum,stack_frame):
         """Sigint handler for threaded apps.
 
         This is a horrible hack to pass information about SIGINT _without_
         using exceptions, since I haven't been able to properly manage
         cross-thread exceptions in GTK/WX.  In fact, I don't think it can be
         done (or at least that's my understanding from a c.l.py thread where
         this was discussed)."""
 
         global KBINT
 
         if CODE_RUN:
             _async_raise(MAIN_THREAD_ID,KeyboardInterrupt)
         else:
             KBINT = True
             print '\nKeyboardInterrupt - Press <Enter> to continue.',
             Term.cout.flush()
 
 else:
     def sigint_handler (signum,stack_frame):
         """Sigint handler for threaded apps.
 
         This is a horrible hack to pass information about SIGINT _without_
         using exceptions, since I haven't been able to properly manage
         cross-thread exceptions in GTK/WX.  In fact, I don't think it can be
         done (or at least that's my understanding from a c.l.py thread where
         this was discussed)."""
 
         global KBINT
 
         print '\nKeyboardInterrupt - Press <Enter> to continue.',
         Term.cout.flush()
         # Set global flag so that runsource can know that Ctrl-C was hit
         KBINT = True
 
 
 class MTInteractiveShell(InteractiveShell):
     """Simple multi-threaded shell."""
 
     # Threading strategy taken from:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/65109, by Brian
     # McErlean and John Finlay.  Modified with corrections by Antoon Pardon,
     # from the pygtk mailing list, to avoid lockups with system calls.
 
     # class attribute to indicate whether the class supports threads or not.
     # Subclasses with thread support should override this as needed.
     isthreaded = True
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None,banner2='',
                  gui_timeout=GUI_TIMEOUT,**kw):
         """Similar to the normal InteractiveShell, but with threading control"""
         
         InteractiveShell.__init__(self,name,usage,rc,user_ns,
                                   user_global_ns,banner2)
 
         # Timeout we wait for GUI thread
         self.gui_timeout = gui_timeout
 
         # A queue to hold the code to be executed. 
         self.code_queue = Queue.Queue()
 
         # Stuff to do at closing time
         self._kill = None
         on_kill = kw.get('on_kill', [])
         # Check that all things to kill are callable:
         for t in on_kill:
             if not callable(t):
                 raise TypeError,'on_kill must be a list of callables'
         self.on_kill = on_kill
         # thread identity of the "worker thread" (that may execute code directly)
         self.worker_ident = None
         
     def runsource(self, source, filename="<input>", symbol="single"):
         """Compile and run some source in the interpreter.
 
         Modified version of code.py's runsource(), to handle threading issues.
         See the original for full docstring details."""
-        
+                
         global KBINT
         
         # If Ctrl-C was typed, we reset the flag and return right away
         if KBINT:
             KBINT = False
             return False
 
         if self._kill:
             # can't queue new code if we are being killed
             return True
         
         try:
             code = self.compile(source, filename, symbol)
         except (OverflowError, SyntaxError, ValueError):
             # Case 1
             self.showsyntaxerror(filename)
             return False
 
         if code is None:
             # Case 2
             return True
 
         # shortcut - if we are in worker thread, or the worker thread is not
         # running, execute directly (to allow recursion and prevent deadlock if
         # code is run early in IPython construction)
         
         if (self.worker_ident is None
             or self.worker_ident == thread.get_ident() ):
             InteractiveShell.runcode(self,code)
-            return
+            return False
 
         # Case 3
         # Store code in queue, so the execution thread can handle it.
 
         completed_ev, received_ev = threading.Event(), threading.Event() 
         
         self.code_queue.put((code,completed_ev, received_ev))
         # first make sure the message was received, with timeout
         received_ev.wait(self.gui_timeout)
         if not received_ev.isSet():
             # the mainloop is dead, start executing code directly
             print "Warning: Timeout for mainloop thread exceeded"
             print "switching to nonthreaded mode (until mainloop wakes up again)"
             self.worker_ident = None
         else:
             completed_ev.wait()
         return False
 
     def runcode(self):
         """Execute a code object.
 
         Multithreaded wrapper around IPython's runcode()."""
         
         global CODE_RUN
         
         # we are in worker thread, stash out the id for runsource() 
         self.worker_ident = thread.get_ident()
 
         if self._kill:
             print >>Term.cout, 'Closing threads...',
             Term.cout.flush()
             for tokill in self.on_kill:
                 tokill()
             print >>Term.cout, 'Done.'
             # allow kill() to return
             self._kill.set()
             return True
 
         # Install sigint handler.  We do it every time to ensure that if user
         # code modifies it, we restore our own handling.
         try:
             signal(SIGINT,sigint_handler)
         except SystemError:
             # This happens under Windows, which seems to have all sorts
             # of problems with signal handling.  Oh well...
             pass
 
         # Flush queue of pending code by calling the run methood of the parent
         # class with all items which may be in the queue.
         code_to_run = None
         while 1:
             try:
                 code_to_run, completed_ev, received_ev = self.code_queue.get_nowait()                
             except Queue.Empty:
                 break
             received_ev.set()
             
             # Exceptions need to be raised differently depending on which
             # thread is active.  This convoluted try/except is only there to
             # protect against asynchronous exceptions, to ensure that a KBINT
             # at the wrong time doesn't deadlock everything.  The global
             # CODE_TO_RUN is set to true/false as close as possible to the
             # runcode() call, so that the KBINT handler is correctly informed.
             try:
                 try:
                    CODE_RUN = True
                    InteractiveShell.runcode(self,code_to_run)
                 except KeyboardInterrupt:
                    print "Keyboard interrupted in mainloop"
                    while not self.code_queue.empty():
                       code, ev1,ev2 = self.code_queue.get_nowait()
                       ev1.set()
                       ev2.set()                      
                    break
             finally:
                 CODE_RUN = False
                 # allow runsource() return from wait
                 completed_ev.set()
                 
         
         # This MUST return true for gtk threading to work
         return True
 
     def kill(self):
         """Kill the thread, returning when it has been shut down."""
         self._kill = threading.Event()
         self._kill.wait()
 
 class MatplotlibShellBase:
     """Mixin class to provide the necessary modifications to regular IPython
     shell classes for matplotlib support.
 
     Given Python's MRO, this should be used as the FIRST class in the
     inheritance hierarchy, so that it overrides the relevant methods."""
     
     def _matplotlib_config(self,name,user_ns,user_global_ns=None):
         """Return items needed to setup the user's shell with matplotlib"""
 
         # Initialize matplotlib to interactive mode always
         import matplotlib
         from matplotlib import backends
         matplotlib.interactive(True)
 
         def use(arg):
             """IPython wrapper for matplotlib's backend switcher.
 
             In interactive use, we can not allow switching to a different
             interactive backend, since thread conflicts will most likely crash
             the python interpreter.  This routine does a safety check first,
             and refuses to perform a dangerous switch.  It still allows
             switching to non-interactive backends."""
 
             if arg in backends.interactive_bk and arg != self.mpl_backend:
                 m=('invalid matplotlib backend switch.\n'
                    'This script attempted to switch to the interactive '
                    'backend: `%s`\n'
                    'Your current choice of interactive backend is: `%s`\n\n'
                    'Switching interactive matplotlib backends at runtime\n'
                    'would crash the python interpreter, '
                    'and IPython has blocked it.\n\n'
                    'You need to either change your choice of matplotlib backend\n'
                    'by editing your .matplotlibrc file, or run this script as a \n'
                    'standalone file from the command line, not using IPython.\n' %
                    (arg,self.mpl_backend) )
                 raise RuntimeError, m
             else:
                 self.mpl_use(arg)
                 self.mpl_use._called = True
         
         self.matplotlib = matplotlib
         self.mpl_backend = matplotlib.rcParams['backend']
 
         # we also need to block switching of interactive backends by use()
         self.mpl_use = matplotlib.use
         self.mpl_use._called = False
         # overwrite the original matplotlib.use with our wrapper
         matplotlib.use = use
 
         # This must be imported last in the matplotlib series, after
         # backend/interactivity choices have been made
         import matplotlib.pylab as pylab
         self.pylab = pylab
 
         self.pylab.show._needmain = False
         # We need to detect at runtime whether show() is called by the user.
         # For this, we wrap it into a decorator which adds a 'called' flag.
         self.pylab.draw_if_interactive = flag_calls(self.pylab.draw_if_interactive)
 
         # Build a user namespace initialized with matplotlib/matlab features.
         user_ns, user_global_ns = IPython.ipapi.make_user_namespaces(user_ns,
             user_global_ns)
 
         # Import numpy as np/pyplot as plt are conventions we're trying to
         # somewhat standardize on.  Making them available to users by default
         # will greatly help this. 
         exec ("import numpy\n"
               "import numpy as np\n"
               "import matplotlib\n"
               "import matplotlib.pylab as pylab\n"
               "try:\n"
               "    import matplotlib.pyplot as plt\n"
               "except ImportError:\n"
               "    pass\n"
               ) in user_ns
         
         # Build matplotlib info banner
         b="""
   Welcome to pylab, a matplotlib-based Python environment.
   For more information, type 'help(pylab)'.
 """
         return user_ns,user_global_ns,b
 
     def mplot_exec(self,fname,*where,**kw):
         """Execute a matplotlib script.
 
         This is a call to execfile(), but wrapped in safeties to properly
         handle interactive rendering and backend switching."""
 
         #print '*** Matplotlib runner ***' # dbg
         # turn off rendering until end of script
         isInteractive = self.matplotlib.rcParams['interactive']
         self.matplotlib.interactive(False)
         self.safe_execfile(fname,*where,**kw)
         self.matplotlib.interactive(isInteractive)
         # make rendering call now, if the user tried to do it
         if self.pylab.draw_if_interactive.called:
             self.pylab.draw()
             self.pylab.draw_if_interactive.called = False
                 
         # if a backend switch was performed, reverse it now
         if self.mpl_use._called:
             self.matplotlib.rcParams['backend'] = self.mpl_backend
-        
+
+    @testdec.skip_doctest
     def magic_run(self,parameter_s=''):
         Magic.magic_run(self,parameter_s,runner=self.mplot_exec)
 
     # Fix the docstring so users see the original as well
     magic_run.__doc__ = "%s\n%s" % (Magic.magic_run.__doc__,
                                     "\n        *** Modified %run for Matplotlib,"
                                     " with proper interactive handling ***")
 
 # Now we provide 2 versions of a matplotlib-aware IPython base shells, single
 # and multithreaded.  Note that these are meant for internal use, the IPShell*
 # classes below are the ones meant for public consumption.
 
 class MatplotlibShell(MatplotlibShellBase,InteractiveShell):
     """Single-threaded shell with matplotlib support."""
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None,**kw):
         user_ns,user_global_ns,b2 = self._matplotlib_config(name,user_ns,user_global_ns)
         InteractiveShell.__init__(self,name,usage,rc,user_ns,user_global_ns,
                                   banner2=b2,**kw)
 
 class MatplotlibMTShell(MatplotlibShellBase,MTInteractiveShell):
     """Multi-threaded shell with matplotlib support."""
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None, **kw):
         user_ns,user_global_ns,b2 = self._matplotlib_config(name,user_ns,user_global_ns)
         MTInteractiveShell.__init__(self,name,usage,rc,user_ns,user_global_ns,
                                     banner2=b2,**kw)
 
 #-----------------------------------------------------------------------------
 # Utility functions for the different GUI enabled IPShell* classes.
 
 def get_tk():
     """Tries to import Tkinter and returns a withdrawn Tkinter root
     window.  If Tkinter is already imported or not available, this
     returns None.  This function calls `hijack_tk` underneath.
     """
     if not USE_TK or sys.modules.has_key('Tkinter'):
         return None
     else:
         try:
             import Tkinter
         except ImportError:
             return None
         else:
             hijack_tk()
             r = Tkinter.Tk()
             r.withdraw()
             return r
 
 def hijack_tk():
     """Modifies Tkinter's mainloop with a dummy so when a module calls
     mainloop, it does not block.
 
     """
     def misc_mainloop(self, n=0):
         pass
     def tkinter_mainloop(n=0):
         pass
     
     import Tkinter
     Tkinter.Misc.mainloop = misc_mainloop
     Tkinter.mainloop = tkinter_mainloop
 
 def update_tk(tk):
     """Updates the Tkinter event loop.  This is typically called from
     the respective WX or GTK mainloops.
     """    
     if tk:
         tk.update()
 
 def hijack_wx():
     """Modifies wxPython's MainLoop with a dummy so user code does not
     block IPython.  The hijacked mainloop function is returned.
     """    
     def dummy_mainloop(*args, **kw):
         pass
 
     try:
         import wx
     except ImportError:
         # For very old versions of WX
         import wxPython as wx
         
     ver = wx.__version__
     orig_mainloop = None
     if ver[:3] >= '2.5':
         import wx
         if hasattr(wx, '_core_'): core = getattr(wx, '_core_')
         elif hasattr(wx, '_core'): core = getattr(wx, '_core')
         else: raise AttributeError('Could not find wx core module')
         orig_mainloop = core.PyApp_MainLoop
         core.PyApp_MainLoop = dummy_mainloop
     elif ver[:3] == '2.4':
         orig_mainloop = wx.wxc.wxPyApp_MainLoop
         wx.wxc.wxPyApp_MainLoop = dummy_mainloop
     else:
         warn("Unable to find either wxPython version 2.4 or >= 2.5.")
     return orig_mainloop
 
 def hijack_gtk():
     """Modifies pyGTK's mainloop with a dummy so user code does not
     block IPython.  This function returns the original `gtk.mainloop`
     function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     import gtk
     if gtk.pygtk_version >= (2,4,0): orig_mainloop = gtk.main
     else:                            orig_mainloop = gtk.mainloop
     gtk.mainloop = dummy_mainloop
     gtk.main = dummy_mainloop
     return orig_mainloop
 
 def hijack_qt():
     """Modifies PyQt's mainloop with a dummy so user code does not 
     block IPython.  This function returns the original 
     `qt.qApp.exec_loop` function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     import qt
     orig_mainloop = qt.qApp.exec_loop
     qt.qApp.exec_loop = dummy_mainloop
     qt.QApplication.exec_loop = dummy_mainloop
     return orig_mainloop
 
 def hijack_qt4():
     """Modifies PyQt4's mainloop with a dummy so user code does not
     block IPython.  This function returns the original 
     `QtGui.qApp.exec_` function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     from PyQt4 import QtGui, QtCore
     orig_mainloop = QtGui.qApp.exec_
     QtGui.qApp.exec_ = dummy_mainloop
     QtGui.QApplication.exec_ = dummy_mainloop
     QtCore.QCoreApplication.exec_ = dummy_mainloop
     return orig_mainloop
 
 #-----------------------------------------------------------------------------
 # The IPShell* classes below are the ones meant to be run by external code as
 # IPython instances.  Note that unless a specific threading strategy is
 # desired, the factory function start() below should be used instead (it
 # selects the proper threaded class).
 
 class IPThread(threading.Thread):
     def run(self):
         self.IP.mainloop(self._banner)
         self.IP.kill()
 
 class IPShellGTK(IPThread):
     """Run a gtk mainloop() in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     GTK timeout callback."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=MTInteractiveShell):
 
         import gtk
+        # Check for set_interactive, coming up in new pygtk.
+        # Disable it so that this code works, but notify 
+        # the user that he has a better option as well.
+        # XXX TODO better support when set_interactive is released
+        try:
+            gtk.set_interactive(False)
+            print "Your PyGtk has set_interactive(), so you can use the"
+            print "more stable single-threaded Gtk mode."
+            print "See https://bugs.launchpad.net/ipython/+bug/270856"
+        except AttributeError:
+            pass
         
         self.gtk = gtk
         self.gtk_mainloop = hijack_gtk()
 
         # Allows us to use both Tk and GTK.
         self.tk = get_tk()
         
         if gtk.pygtk_version >= (2,4,0): mainquit = self.gtk.main_quit
         else:                            mainquit = self.gtk.mainquit
 
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[mainquit])
 
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
 
         threading.Thread.__init__(self)
 
     def mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         if self.gtk.pygtk_version >= (2,4,0):
             import gobject
             gobject.idle_add(self.on_timer)
         else:
             self.gtk.idle_add(self.on_timer)
 
         if sys.platform != 'win32':
             try:
                 if self.gtk.gtk_version[0] >= 2:
                     self.gtk.gdk.threads_init()
             except AttributeError:
                 pass
             except RuntimeError:
                 error('Your pyGTK likely has not been compiled with '
                       'threading support.\n'
                       'The exception printout is below.\n'
                       'You can either rebuild pyGTK with threads, or '
                       'try using \n'
                       'matplotlib with a different backend (like Tk or WX).\n'
                       'Note that matplotlib will most likely not work in its '
                       'current state!')
                 self.IP.InteractiveTB()
 
         self.start()
         self.gtk.gdk.threads_enter()
         self.gtk_mainloop()
         self.gtk.gdk.threads_leave()
         self.join()
 
     def on_timer(self):
         """Called when GTK is idle.
 
         Must return True always, otherwise GTK stops calling it"""
         
         update_tk(self.tk)
         self.IP.runcode()
         time.sleep(0.01)
         return True
 
 
 class IPShellWX(IPThread):
     """Run a wx mainloop() in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     GTK timeout callback."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=MTInteractiveShell):
 
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[self.wxexit])
 
         wantedwxversion=self.IP.rc.wxversion
         if wantedwxversion!="0":
             try:
                 import wxversion
             except ImportError:
                 error('The wxversion module is needed for WX version selection')
             else:
                 try:
                     wxversion.select(wantedwxversion)
                 except:
                     self.IP.InteractiveTB()
                     error('Requested wxPython version %s could not be loaded' %
                                                                wantedwxversion)
 
         import wx
 
         threading.Thread.__init__(self)
         self.wx = wx
         self.wx_mainloop = hijack_wx()
 
         # Allows us to use both Tk and GTK.
         self.tk = get_tk()
         
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
 
         self.app = None
 
     def wxexit(self, *args):
         if self.app is not None:
             self.app.agent.timer.Stop()
             self.app.ExitMainLoop()
 
     def mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         self.start()
 
         class TimerAgent(self.wx.MiniFrame):
             wx = self.wx
             IP = self.IP
             tk = self.tk
             def __init__(self, parent, interval):
                 style = self.wx.DEFAULT_FRAME_STYLE | self.wx.TINY_CAPTION_HORIZ
                 self.wx.MiniFrame.__init__(self, parent, -1, ' ', pos=(200, 200),
                                              size=(100, 100),style=style)
                 self.Show(False)
                 self.interval = interval
                 self.timerId = self.wx.NewId()                                
 
             def StartWork(self):
                 self.timer = self.wx.Timer(self, self.timerId)
                 self.wx.EVT_TIMER(self,  self.timerId, self.OnTimer)
                 self.timer.Start(self.interval)
 
             def OnTimer(self, event):
                 update_tk(self.tk)
                 self.IP.runcode()
 
         class App(self.wx.App):
             wx = self.wx
             TIMEOUT = self.TIMEOUT
             def OnInit(self):
                 'Create the main window and insert the custom frame'
                 self.agent = TimerAgent(None, self.TIMEOUT)
                 self.agent.Show(False)
                 self.agent.StartWork()
                 return True
 
         self.app = App(redirect=False)
         self.wx_mainloop(self.app)
         self.join()
 
 
 class IPShellQt(IPThread):
     """Run a Qt event loop in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     Qt timer / slot."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self, argv=None, user_ns=None, user_global_ns=None,
                  debug=0, shell_class=MTInteractiveShell):
 
         import qt
 
         self.exec_loop = hijack_qt()
 
         # Allows us to use both Tk and QT.
         self.tk = get_tk()
 
         self.IP = make_IPython(argv,
                                user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[qt.qApp.exit])
 
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
         
         threading.Thread.__init__(self)
 
     def mainloop(self, sys_exit=0, banner=None):
 
         import qt
 
         self._banner = banner
 
         if qt.QApplication.startingUp():
             a = qt.QApplication(sys.argv)
 
         self.timer = qt.QTimer()
         qt.QObject.connect(self.timer,
                            qt.SIGNAL('timeout()'),
                            self.on_timer)
 
         self.start()
         self.timer.start(self.TIMEOUT, True)
         while True:
             if self.IP._kill: break
             self.exec_loop()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         result = self.IP.runcode()
         self.timer.start(self.TIMEOUT, True)
         return result
 
 
 class IPShellQt4(IPThread):
     """Run a Qt event loop in a separate thread.
 
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     Qt timer / slot."""
 
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self, argv=None, user_ns=None, user_global_ns=None,
                  debug=0, shell_class=MTInteractiveShell):
 
         from PyQt4 import QtCore, QtGui
 
         try:
             # present in PyQt4-4.2.1 or later
             QtCore.pyqtRemoveInputHook()
         except AttributeError:
             pass
 
         if QtCore.PYQT_VERSION_STR == '4.3':
             warn('''PyQt4 version 4.3 detected.
 If you experience repeated threading warnings, please update PyQt4.
 ''')
 
         self.exec_ = hijack_qt4()
 
         # Allows us to use both Tk and QT.
         self.tk = get_tk()
 
         self.IP = make_IPython(argv,
                                user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[QtGui.qApp.exit])
 
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None
 
         threading.Thread.__init__(self)
 
     def mainloop(self, sys_exit=0, banner=None):
 
         from PyQt4 import QtCore, QtGui
 
         self._banner = banner
 
         if QtGui.QApplication.startingUp():
             a = QtGui.QApplication(sys.argv)
 
         self.timer = QtCore.QTimer()
         QtCore.QObject.connect(self.timer,
                                QtCore.SIGNAL('timeout()'),
                                self.on_timer)
 
         self.start()
         self.timer.start(self.TIMEOUT)
         while True:
             if self.IP._kill: break
             self.exec_()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         result = self.IP.runcode()
         self.timer.start(self.TIMEOUT)
         return result
 
 
 # A set of matplotlib public IPython shell classes, for single-threaded (Tk*
 # and FLTK*) and multithreaded (GTK*, WX* and Qt*) backends to use.
 def _load_pylab(user_ns):
     """Allow users to disable pulling all of pylab into the top-level
     namespace.
 
     This little utility must be called AFTER the actual ipython instance is
     running, since only then will the options file have been fully parsed."""
     
     ip = IPython.ipapi.get()
     if ip.options.pylab_import_all:
         ip.ex("from matplotlib.pylab import *")
         ip.IP.user_config_ns.update(ip.user_ns)
         
 
 class IPShellMatplotlib(IPShell):
     """Subclass IPShell with MatplotlibShell as the internal shell.
 
     Single-threaded class, meant for the Tk* and FLTK* backends.
 
     Having this on a separate class simplifies the external driver code."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShell.__init__(self,argv,user_ns,user_global_ns,debug,
                          shell_class=MatplotlibShell)
         _load_pylab(self.IP.user_ns)
 
 class IPShellMatplotlibGTK(IPShellGTK):
     """Subclass IPShellGTK with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the GTK* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellGTK.__init__(self,argv,user_ns,user_global_ns,debug,
                             shell_class=MatplotlibMTShell)
         _load_pylab(self.IP.user_ns)
 
 class IPShellMatplotlibWX(IPShellWX):
     """Subclass IPShellWX with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the WX* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellWX.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
         _load_pylab(self.IP.user_ns)
 
 class IPShellMatplotlibQt(IPShellQt):
     """Subclass IPShellQt with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the Qt* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellQt.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
         _load_pylab(self.IP.user_ns)
 
 class IPShellMatplotlibQt4(IPShellQt4):
     """Subclass IPShellQt4 with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the Qt4* backends."""
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellQt4.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
         _load_pylab(self.IP.user_ns)
 
 #-----------------------------------------------------------------------------
 # Factory functions to actually start the proper thread-aware shell
 
 def _select_shell(argv):
     """Select a shell from the given argv vector.
 
     This function implements the threading selection policy, allowing runtime
     control of the threading mode, both for general users and for matplotlib.
 
     Return:
       Shell class to be instantiated for runtime operation.
     """
     
     global USE_TK
 
     mpl_shell = {'gthread' : IPShellMatplotlibGTK,
                  'wthread' : IPShellMatplotlibWX,
                  'qthread' : IPShellMatplotlibQt,
                  'q4thread' : IPShellMatplotlibQt4,
                  'tkthread' : IPShellMatplotlib,  # Tk is built-in
                  }
 
     th_shell = {'gthread' : IPShellGTK,
                 'wthread' : IPShellWX,
                 'qthread' : IPShellQt,
                 'q4thread' : IPShellQt4,
                 'tkthread' : IPShell, # Tk is built-in
                 }
 
     backends = {'gthread' : 'GTKAgg',
                 'wthread' : 'WXAgg',
                 'qthread' : 'QtAgg',
                 'q4thread' :'Qt4Agg',
                 'tkthread' :'TkAgg',
                 }
 
     all_opts = set(['tk','pylab','gthread','qthread','q4thread','wthread',
                     'tkthread'])
     user_opts = set([s.replace('-','') for s in argv[:3]])
     special_opts = user_opts & all_opts            
 
     if 'tk' in special_opts:
         USE_TK = True
         special_opts.remove('tk')
 
     if 'pylab' in special_opts:
 
         try:
             import matplotlib
         except ImportError:
             error('matplotlib could NOT be imported!  Starting normal IPython.')
             return IPShell
         
         special_opts.remove('pylab')
         # If there's any option left, it means the user wants to force the
         # threading backend, else it's auto-selected from the rc file
         if special_opts:
             th_mode = special_opts.pop()
             matplotlib.rcParams['backend'] = backends[th_mode]
         else:
             backend = matplotlib.rcParams['backend']
             if backend.startswith('GTK'):
                 th_mode = 'gthread'
             elif backend.startswith('WX'):
                 th_mode = 'wthread'
             elif backend.startswith('Qt4'):
                 th_mode = 'q4thread'
             elif backend.startswith('Qt'):
                 th_mode = 'qthread'
             else:
                 # Any other backend, use plain Tk
                 th_mode = 'tkthread'
                 
         return mpl_shell[th_mode]
     else:
         # No pylab requested, just plain threads
         try:
             th_mode = special_opts.pop()
         except KeyError:
             th_mode = 'tkthread'
         return th_shell[th_mode]
 
 
 # This is the one which should be called by external code.
 def start(user_ns = None):
     """Return a running shell instance, dealing with threading options.
 
     This is a factory function which will instantiate the proper IPython shell
     based on the user's threading choice.  Such a selector is needed because
     different GUI toolkits require different thread handling details."""
 
     shell = _select_shell(sys.argv)
     return shell(user_ns = user_ns)
 
 # Some aliases for backwards compatibility
 IPythonShell = IPShell
 IPythonShellEmbed = IPShellEmbed
 #************************ End of file <Shell.py> ***************************

IPython/UserConfig/ipythonrc-physics

@@ -1,43 +1,45
 # -*- Mode: Shell-Script -*-  Not really, but shows comments correctly
 #***************************************************************************
 #
 # Configuration file for ipython -- ipythonrc format
 #
 # The format of this file is one of 'key value' lines.
 # Lines containing only whitespace at the beginning and then a # are ignored
 # as comments. But comments can NOT be put on lines with data.
 #***************************************************************************
 
 # If this file is found in the user's ~/.ipython directory as
 # ipythonrc-physics, it can be loaded by calling passing the '-profile
 # physics' (or '-p physics') option to IPython.
 
 # This profile loads modules useful for doing interactive calculations with
 # physical quantities (with units). It relies on modules from Konrad Hinsen's
 # ScientificPython (http://dirac.cnrs-orleans.fr/ScientificPython/)
 
 # First load basic user configuration
 include ipythonrc
 
 # import ...
 # Module with alternate input syntax for PhysicalQuantity objects.
 import_mod IPython.Extensions.PhysicalQInput
 
 # from ... import *
 # math CANNOT be imported after PhysicalQInteractive. It will override the
 # functions defined there.
 import_all math IPython.Extensions.PhysicalQInteractive
 
 # from ... import ...
 import_some  
 
 # code
 execute q = PhysicalQuantityInteractive
 execute g = PhysicalQuantityInteractive('9.8 m/s**2')
 ececute rad = pi/180.
 execute print '*** q is an alias for PhysicalQuantityInteractive'
 execute print '*** g = 9.8 m/s^2 has been defined'
 execute print '*** rad = pi/180  has been defined'
+execute import ipy_constants as C
+execute print '*** C is the physical constants module'
 
 # Files to execute
 execfile 

IPython/completer.py

@@ -1,637 +1,640
 """Word completion for IPython.
 
 This module is a fork of the rlcompleter module in the Python standard
 library.  The original enhancements made to rlcompleter have been sent
 upstream and were accepted as of Python 2.3, but we need a lot more
 functionality specific to IPython, so this module will continue to live as an
 IPython-specific utility.
 
 ---------------------------------------------------------------------------
 Original rlcompleter documentation:
 
 This requires the latest extension to the readline module (the
 completes keywords, built-ins and globals in __main__; when completing
 NAME.NAME..., it evaluates (!) the expression up to the last dot and
 completes its attributes.
 
 It's very cool to do "import string" type "string.", hit the
 completion key (twice), and see the list of names defined by the
 string module!
 
 Tip: to use the tab key as the completion key, call
 
     readline.parse_and_bind("tab: complete")
 
 Notes:
 
 - Exceptions raised by the completer function are *ignored* (and
 generally cause the completion to fail).  This is a feature -- since
 readline sets the tty device in raw (or cbreak) mode, printing a
 traceback wouldn't work well without some complicated hoopla to save,
 reset and restore the tty state.
 
 - The evaluation of the NAME.NAME... form may cause arbitrary
 application defined code to be executed if an object with a
 __getattr__ hook is found.  Since it is the responsibility of the
 application (or the user) to enable this feature, I consider this an
 acceptable risk.  More complicated expressions (e.g. function calls or
 indexing operations) are *not* evaluated.
 
 - GNU readline is also used by the built-in functions input() and
 raw_input(), and thus these also benefit/suffer from the completer
 features.  Clearly an interactive application can benefit by
 specifying its own completer function and using raw_input() for all
 its input.
 
 - When the original stdin is not a tty device, GNU readline is never
 used, and this module (and the readline module) are silently inactive.
 
 """
 
 #*****************************************************************************
 #
 # Since this file is essentially a minimally modified copy of the rlcompleter
 # module which is part of the standard Python distribution, I assume that the
 # proper procedure is to maintain its copyright as belonging to the Python
 # Software Foundation (in addition to my own, for all new code).
 #
 #       Copyright (C) 2001 Python Software Foundation, www.python.org
 #       Copyright (C) 2001-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.
 #
 #*****************************************************************************
 
 import __builtin__
 import __main__
 import glob
 import keyword
 import os
 import re
 import shlex
 import sys
 import IPython.rlineimpl as readline    
 import itertools
 from IPython.ipstruct import Struct
 from IPython import ipapi
 from IPython import generics
 import types
 
 # Python 2.4 offers sets as a builtin
 try:
     set()
 except NameError:
     from sets import Set as set
 
 from IPython.genutils import debugx, dir2
 
 __all__ = ['Completer','IPCompleter']
 
 class Completer:
     def __init__(self,namespace=None,global_namespace=None):
         """Create a new completer for the command line.
 
         Completer([namespace,global_namespace]) -> completer instance.
 
         If unspecified, the default namespace where completions are performed
         is __main__ (technically, __main__.__dict__). Namespaces should be
         given as dictionaries.
 
         An optional second namespace can be given.  This allows the completer
         to handle cases where both the local and global scopes need to be
         distinguished.
 
         Completer instances should be used as the completion mechanism of
         readline via the set_completer() call:
 
         readline.set_completer(Completer(my_namespace).complete)
         """
 
         # Don't bind to namespace quite yet, but flag whether the user wants a
         # specific namespace or to use __main__.__dict__. This will allow us
         # to bind to __main__.__dict__ at completion time, not now.
         if namespace is None:
             self.use_main_ns = 1
         else:
             self.use_main_ns = 0
             self.namespace = namespace
 
         # The global namespace, if given, can be bound directly
         if global_namespace is None:
             self.global_namespace = {}
         else:
             self.global_namespace = global_namespace
 
     def complete(self, text, state):
         """Return the next possible completion for 'text'.
 
         This is called successively with state == 0, 1, 2, ... until it
         returns None.  The completion should begin with 'text'.
 
         """
         if self.use_main_ns:
             self.namespace = __main__.__dict__
             
         if state == 0:
             if "." in text:
                 self.matches = self.attr_matches(text)
             else:
                 self.matches = self.global_matches(text)
         try:
             return self.matches[state]
         except IndexError:
             return None
 
     def global_matches(self, text):
         """Compute matches when text is a simple name.
 
         Return a list of all keywords, built-in functions and names currently
         defined in self.namespace or self.global_namespace that match.
 
         """
         matches = []
         match_append = matches.append
         n = len(text)
         for lst in [keyword.kwlist,
                     __builtin__.__dict__.keys(),
                     self.namespace.keys(),
                     self.global_namespace.keys()]:
             for word in lst:
                 if word[:n] == text and word != "__builtins__":
                     match_append(word)
         return matches
 
     def attr_matches(self, text):
         """Compute matches when text contains a dot.
 
         Assuming the text is of the form NAME.NAME....[NAME], and is
         evaluatable in self.namespace or self.global_namespace, it will be
         evaluated and its attributes (as revealed by dir()) are used as
         possible completions.  (For class instances, class members are are
         also considered.)
 
         WARNING: this can still invoke arbitrary C code, if an object
         with a __getattr__ hook is evaluated.
 
         """
         import re
 
         # Another option, seems to work great. Catches things like ''.<tab>
         m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
 
         if not m:
             return []
         
         expr, attr = m.group(1, 3)
         try:
             obj = eval(expr, self.namespace)
         except:
             try:
                 obj = eval(expr, self.global_namespace)
             except:
                 return []
 
         words = dir2(obj)
         
         try:
             words = generics.complete_object(obj, words)
         except ipapi.TryNext:
             pass
         # Build match list to return
         n = len(attr)
         res = ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
         return res
 
 class IPCompleter(Completer):
     """Extension of the completer class with IPython-specific features"""
 
     def __init__(self,shell,namespace=None,global_namespace=None,
                  omit__names=0,alias_table=None):
         """IPCompleter() -> completer
 
         Return a completer object suitable for use by the readline library
         via readline.set_completer().
 
         Inputs:
 
         - shell: a pointer to the ipython shell itself.  This is needed
         because this completer knows about magic functions, and those can
         only be accessed via the ipython instance.
 
         - namespace: an optional dict where completions are performed.
 
         - global_namespace: secondary optional dict for completions, to
         handle cases (such as IPython embedded inside functions) where
         both Python scopes are visible.
 
         - The optional omit__names parameter sets the completer to omit the
         'magic' names (__magicname__) for python objects unless the text
         to be completed explicitly starts with one or more underscores.
 
         - If alias_table is supplied, it should be a dictionary of aliases
         to complete. """
 
         Completer.__init__(self,namespace,global_namespace)
         self.magic_prefix = shell.name+'.magic_'
         self.magic_escape = shell.ESC_MAGIC
         self.readline = readline
         delims = self.readline.get_completer_delims()
         delims = delims.replace(self.magic_escape,'')
         self.readline.set_completer_delims(delims)
         self.get_line_buffer = self.readline.get_line_buffer
         self.get_endidx = self.readline.get_endidx
         self.omit__names = omit__names
         self.merge_completions = shell.rc.readline_merge_completions        
         if alias_table is None:
             alias_table = {}
         self.alias_table = alias_table
         # Regexp to split filenames with spaces in them
         self.space_name_re = re.compile(r'([^\\] )')
         # Hold a local ref. to glob.glob for speed
         self.glob = glob.glob
 
         # Determine if we are running on 'dumb' terminals, like (X)Emacs
         # buffers, to avoid completion problems.
         term = os.environ.get('TERM','xterm')
         self.dumb_terminal = term in ['dumb','emacs']
         
         # Special handling of backslashes needed in win32 platforms
         if sys.platform == "win32":
             self.clean_glob = self._clean_glob_win32
         else:
             self.clean_glob = self._clean_glob
         self.matchers = [self.python_matches,
                          self.file_matches,
                          self.alias_matches,
                          self.python_func_kw_matches]
 
     
     # Code contributed by Alex Schmolck, for ipython/emacs integration
     def all_completions(self, text):
         """Return all possible completions for the benefit of emacs."""
 
         completions = []
         comp_append = completions.append
         try:
             for i in xrange(sys.maxint):
                 res = self.complete(text, i)
 
                 if not res: break
 
                 comp_append(res)
         #XXX workaround for ``notDefined.<tab>``
         except NameError:
             pass
         return completions
     # /end Alex Schmolck code.
 
     def _clean_glob(self,text):
         return self.glob("%s*" % text)
 
     def _clean_glob_win32(self,text):
         return [f.replace("\\","/")
                 for f in self.glob("%s*" % text)]            
 
     def file_matches(self, text):
         """Match filenames, expanding ~USER type strings.
 
         Most of the seemingly convoluted logic in this completer is an
         attempt to handle filenames with spaces in them.  And yet it's not
         quite perfect, because Python's readline doesn't expose all of the
         GNU readline details needed for this to be done correctly.
 
         For a filename with a space in it, the printed completions will be
         only the parts after what's already been typed (instead of the
         full completions, as is normally done).  I don't think with the
         current (as of Python 2.3) Python readline it's possible to do
         better."""
 
         #print 'Completer->file_matches: <%s>' % text # dbg
 
         # chars that require escaping with backslash - i.e. chars
         # that readline treats incorrectly as delimiters, but we
         # don't want to treat as delimiters in filename matching
         # when escaped with backslash
 
-        protectables = ' '
+        if sys.platform == 'win32':
+            protectables = ' '
+        else:
+            protectables = ' ()'
 
         if text.startswith('!'):
             text = text[1:]
             text_prefix = '!'
         else:
             text_prefix = ''
             
         def protect_filename(s):
             return "".join([(ch in protectables and '\\' + ch or ch)
                             for ch in s])
 
         def single_dir_expand(matches):
             "Recursively expand match lists containing a single dir."
             
             if len(matches) == 1 and os.path.isdir(matches[0]):
                 # Takes care of links to directories also.  Use '/'
                 # explicitly, even under Windows, so that name completions
                 # don't end up escaped.
                 d = matches[0]
                 if d[-1] in ['/','\\']:
                     d = d[:-1]
 
                 subdirs = os.listdir(d)
                 if subdirs:
                     matches = [ (d + '/' + p) for p in subdirs]
                     return single_dir_expand(matches)
                 else:
                     return matches
             else:
                 return matches
         
         lbuf = self.lbuf
         open_quotes = 0  # track strings with open quotes
         try:
             lsplit = shlex.split(lbuf)[-1]
         except ValueError:
             # typically an unmatched ", or backslash without escaped char.
             if lbuf.count('"')==1:
                 open_quotes = 1
                 lsplit = lbuf.split('"')[-1]
             elif lbuf.count("'")==1:
                 open_quotes = 1
                 lsplit = lbuf.split("'")[-1]
             else:
                 return []
         except IndexError:
             # tab pressed on empty line
             lsplit = ""
 
         if lsplit != protect_filename(lsplit):
             # if protectables are found, do matching on the whole escaped
             # name
             has_protectables = 1
             text0,text = text,lsplit
         else:
             has_protectables = 0
             text = os.path.expanduser(text)
 
         if text == "":
             return [text_prefix + protect_filename(f) for f in self.glob("*")]
 
         m0 = self.clean_glob(text.replace('\\',''))
         if has_protectables:
             # If we had protectables, we need to revert our changes to the
             # beginning of filename so that we don't double-write the part
             # of the filename we have so far
             len_lsplit = len(lsplit)
             matches = [text_prefix + text0 + 
                        protect_filename(f[len_lsplit:]) for f in m0]
         else:
             if open_quotes:
                 # if we have a string with an open quote, we don't need to
                 # protect the names at all (and we _shouldn't_, as it
                 # would cause bugs when the filesystem call is made).
                 matches = m0
             else:
                 matches = [text_prefix + 
                            protect_filename(f) for f in m0]
 
         #print 'mm',matches  # dbg
         return single_dir_expand(matches)
 
     def alias_matches(self, text):
         """Match internal system aliases"""        
         #print 'Completer->alias_matches:',text,'lb',self.lbuf # dbg
         
         # if we are not in the first 'item', alias matching 
         # doesn't make sense - unless we are starting with 'sudo' command.
         if ' ' in self.lbuf.lstrip() and not self.lbuf.lstrip().startswith('sudo'):
             return []
         text = os.path.expanduser(text)
         aliases =  self.alias_table.keys()
         if text == "":
             return aliases
         else:
             return [alias for alias in aliases if alias.startswith(text)]
 
     def python_matches(self,text):
         """Match attributes or global python names"""
 
         #print 'Completer->python_matches, txt=<%s>' % text # dbg
         if "." in text:
             try:
                 matches = self.attr_matches(text)
                 if text.endswith('.') and self.omit__names:
                     if self.omit__names == 1:
                         # true if txt is _not_ a __ name, false otherwise:
                         no__name = (lambda txt:
                                     re.match(r'.*\.__.*?__',txt) is None)
                     else:
                         # true if txt is _not_ a _ name, false otherwise:
                         no__name = (lambda txt:
                                     re.match(r'.*\._.*?',txt) is None)
                     matches = filter(no__name, matches)
             except NameError:
                 # catches <undefined attributes>.<tab>
                 matches = []
         else:
             matches = self.global_matches(text)
             # this is so completion finds magics when automagic is on:
             if (matches == [] and 
                  not text.startswith(os.sep) and
                  not ' ' in self.lbuf):
                 matches = self.attr_matches(self.magic_prefix+text)
         return matches
 
     def _default_arguments(self, obj):
         """Return the list of default arguments of obj if it is callable,
         or empty list otherwise."""
 
         if not (inspect.isfunction(obj) or inspect.ismethod(obj)):
             # for classes, check for __init__,__new__
             if inspect.isclass(obj):
                 obj = (getattr(obj,'__init__',None) or
                        getattr(obj,'__new__',None))
             # for all others, check if they are __call__able
             elif hasattr(obj, '__call__'):
                 obj = obj.__call__
             # XXX: is there a way to handle the builtins ?
         try:
             args,_,_1,defaults = inspect.getargspec(obj)
             if defaults:
                 return args[-len(defaults):]
         except TypeError: pass
         return []
 
     def python_func_kw_matches(self,text):
         """Match named parameters (kwargs) of the last open function"""
 
         if "." in text: # a parameter cannot be dotted
             return []
         try: regexp = self.__funcParamsRegex
         except AttributeError:
             regexp = self.__funcParamsRegex = re.compile(r'''
                 '.*?' |    # single quoted strings or
                 ".*?" |    # double quoted strings or
                 \w+   |    # identifier
                 \S         # other characters
                 ''', re.VERBOSE | re.DOTALL)
         # 1. find the nearest identifier that comes before an unclosed
         # parenthesis e.g. for "foo (1+bar(x), pa", the candidate is "foo"
         tokens = regexp.findall(self.get_line_buffer())
         tokens.reverse()
         iterTokens = iter(tokens); openPar = 0
         for token in iterTokens:
             if token == ')':
                 openPar -= 1
             elif token == '(':
                 openPar += 1
                 if openPar > 0:
                     # found the last unclosed parenthesis
                     break
         else:
             return []
         # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
         ids = []
         isId = re.compile(r'\w+$').match
         while True:
             try:
                 ids.append(iterTokens.next())
                 if not isId(ids[-1]):
                     ids.pop(); break
                 if not iterTokens.next() == '.':
                     break
             except StopIteration:
                 break
         # lookup the candidate callable matches either using global_matches
         # or attr_matches for dotted names
         if len(ids) == 1:
             callableMatches = self.global_matches(ids[0])
         else:
             callableMatches = self.attr_matches('.'.join(ids[::-1]))
         argMatches = []
         for callableMatch in callableMatches:
             try: namedArgs = self._default_arguments(eval(callableMatch,
                                                          self.namespace))
             except: continue
             for namedArg in namedArgs:
                 if namedArg.startswith(text):
                     argMatches.append("%s=" %namedArg)
         return argMatches
 
     def dispatch_custom_completer(self,text):
         #print "Custom! '%s' %s" % (text, self.custom_completers) # dbg
         line = self.full_lbuf        
         if not line.strip():
             return None
 
         event = Struct()
         event.line = line
         event.symbol = text
         cmd = line.split(None,1)[0]
         event.command = cmd
         #print "\ncustom:{%s]\n" % event # dbg
         
         # for foo etc, try also to find completer for %foo
         if not cmd.startswith(self.magic_escape):
             try_magic = self.custom_completers.s_matches(
               self.magic_escape + cmd)            
         else:
             try_magic = []
         
         
         for c in itertools.chain(
                                  self.custom_completers.s_matches(cmd),
                                  try_magic,
                                  self.custom_completers.flat_matches(self.lbuf)):
             #print "try",c # dbg
             try:
                 res = c(event)
                 # first, try case sensitive match
                 withcase = [r for r in res if r.startswith(text)]
                 if withcase:
                     return withcase
                 # if none, then case insensitive ones are ok too
                 return [r for r in res if r.lower().startswith(text.lower())]
             except ipapi.TryNext:
                 pass
             
         return None
                
     def complete(self, text, state,line_buffer=None):
         """Return the next possible completion for 'text'.
 
         This is called successively with state == 0, 1, 2, ... until it
         returns None.  The completion should begin with 'text'.
 
         :Keywords:
         - line_buffer: string
         If not given, the completer attempts to obtain the current line buffer
         via readline.  This keyword allows clients which are requesting for
         text completions in non-readline contexts to inform the completer of
         the entire text.
         """
 
         #print '\n*** COMPLETE: <%s> (%s)' % (text,state)  # dbg
 
         # if there is only a tab on a line with only whitespace, instead
         # of the mostly useless 'do you want to see all million
         # completions' message, just do the right thing and give the user
         # his tab!  Incidentally, this enables pasting of tabbed text from
         # an editor (as long as autoindent is off).
 
         # It should be noted that at least pyreadline still shows
         # file completions - is there a way around it?
         
         # don't apply this on 'dumb' terminals, such as emacs buffers, so we
         # don't interfere with their own tab-completion mechanism.
         if line_buffer is None:
             self.full_lbuf = self.get_line_buffer()
         else:
             self.full_lbuf = line_buffer
             
         if not (self.dumb_terminal or self.full_lbuf.strip()):
             self.readline.insert_text('\t')
             return None
         
         magic_escape = self.magic_escape
         magic_prefix = self.magic_prefix
 
         self.lbuf = self.full_lbuf[:self.get_endidx()]
 
         try:
             if text.startswith(magic_escape):
                 text = text.replace(magic_escape,magic_prefix)
             elif text.startswith('~'):
                 text = os.path.expanduser(text)
             if state == 0:
                 custom_res = self.dispatch_custom_completer(text)
                 if custom_res is not None:
                     # did custom completers produce something?
                     self.matches = custom_res
                 else:
                     # Extend the list of completions with the results of each
                     # matcher, so we return results to the user from all
                     # namespaces.
                     if self.merge_completions:
                         self.matches = []
                         for matcher in self.matchers:
                             self.matches.extend(matcher(text))
                     else:
                         for matcher in self.matchers:
                             self.matches = matcher(text)
                             if self.matches:
                                 break
                     def uniq(alist):
                         set = {}
                         return [set.setdefault(e,e) for e in alist if e not in set]
                     self.matches = uniq(self.matches)                
             try:
                 ret = self.matches[state].replace(magic_prefix,magic_escape)                
                 return ret
             except IndexError:
                 return None
         except:
             #from IPython.ultraTB import AutoFormattedTB; # dbg
             #tb=AutoFormattedTB('Verbose');tb() #dbg
             
             # If completion fails, don't annoy the user.
             return None

IPython/config/api.py

@@ -1,104 +1,102
 # encoding: utf-8
 
 """This is the official entry point to IPython's configuration system.  """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 os
-from IPython.config.cutils import get_home_dir, get_ipython_dir
+from os.path import join as pjoin
+
+from IPython.genutils import get_home_dir, get_ipython_dir
 from IPython.external.configobj import ConfigObj
 
-# Traitlets config imports
-from IPython.config import traitlets
-from IPython.config.config import *
-from traitlets import *
 
 class ConfigObjManager(object):
     
     def __init__(self, configObj, filename):
         self.current = configObj
         self.current.indent_type = '    '
         self.filename = filename
         # self.write_default_config_file()
         
     def get_config_obj(self):
         return self.current
     
     def update_config_obj(self, newConfig):
         self.current.merge(newConfig)
         
     def update_config_obj_from_file(self, filename):
         newConfig = ConfigObj(filename, file_error=False)
         self.current.merge(newConfig)
         
     def update_config_obj_from_default_file(self, ipythondir=None):
         fname = self.resolve_file_path(self.filename, ipythondir)
         self.update_config_obj_from_file(fname)
 
     def write_config_obj_to_file(self, filename):
         f = open(filename, 'w')
         self.current.write(f)
         f.close()
 
     def write_default_config_file(self):
         ipdir = get_ipython_dir()
-        fname = ipdir + '/' + self.filename
+        fname = pjoin(ipdir, self.filename)
         if not os.path.isfile(fname):
             print "Writing the configuration file to: " + fname
             self.write_config_obj_to_file(fname)
     
     def _import(self, key):
         package = '.'.join(key.split('.')[0:-1])
         obj = key.split('.')[-1]
         execString = 'from %s import %s' % (package, obj)
         exec execString
         exec 'temp = %s' % obj 
         return temp
 
     def resolve_file_path(self, filename, ipythondir = None):
         """Resolve filenames into absolute paths.
 
         This function looks in the following directories in order:
 
         1.  In the current working directory or by absolute path with ~ expanded
         2.  In ipythondir if that is set
         3.  In the IPYTHONDIR environment variable if it exists
         4.  In the ~/.ipython directory
 
         Note: The IPYTHONDIR is also used by the trunk version of IPython so
                changing it will also affect it was well.
         """
 
         # In cwd or by absolute path with ~ expanded
         trythis = os.path.expanduser(filename)
         if os.path.isfile(trythis):
             return trythis
 
         # In ipythondir if it is set
         if ipythondir is not None:
-            trythis = ipythondir + '/' + filename
+            trythis = pjoin(ipythondir, filename)
             if os.path.isfile(trythis):
                 return trythis        
 
-        trythis = get_ipython_dir() + '/' + filename
+        trythis = pjoin(get_ipython_dir(), filename)
         if os.path.isfile(trythis):
             return trythis
 
         return None
 
 
     
     
 
     

IPython/config/cutils.py

@@ -1,99 +1,34
 # encoding: utf-8
 
 """Configuration-related utilities for all IPython."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 os
 import sys
 
 #---------------------------------------------------------------------------
 # Normal code begins
 #---------------------------------------------------------------------------
 
-class HomeDirError(Exception):
-    pass
-
-def get_home_dir():
-    """Return the closest possible equivalent to a 'home' directory.
-
-    We first try $HOME.  Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
-
-    Currently only Posix and NT are implemented, a HomeDirError exception is
-    raised for all other OSes. """
-
-    isdir = os.path.isdir
-    env = os.environ
-    try:
-        homedir = env['HOME']
-        if not isdir(homedir):
-            # in case a user stuck some string which does NOT resolve to a
-            # valid path, it's as good as if we hadn't foud it
-            raise KeyError
-        return homedir
-    except KeyError:
-        if os.name == 'posix':
-            raise HomeDirError,'undefined $HOME, IPython can not proceed.'
-        elif os.name == 'nt':
-            # For some strange reason, win9x returns 'nt' for os.name.
-            try:
-                homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
-                if not isdir(homedir):
-                    homedir = os.path.join(env['USERPROFILE'])
-                    if not isdir(homedir):
-                        raise HomeDirError
-                return homedir
-            except:
-                try:
-                    # Use the registry to get the 'My Documents' folder.
-                    import _winreg as wreg
-                    key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
-                                       "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
-                    homedir = wreg.QueryValueEx(key,'Personal')[0]
-                    key.Close()
-                    if not isdir(homedir):
-                        e = ('Invalid "Personal" folder registry key '
-                             'typically "My Documents".\n'
-                             'Value: %s\n'
-                             'This is not a valid directory on your system.' %
-                             homedir)
-                        raise HomeDirError(e)
-                    return homedir
-                except HomeDirError:
-                    raise
-                except:
-                    return 'C:\\'
-        elif os.name == 'dos':
-            # Desperate, may do absurd things in classic MacOS. May work under DOS.
-            return 'C:\\'
-        else:
-            raise HomeDirError,'support for your operating system not implemented.'
-
-def get_ipython_dir():
-    ipdir_def = '.ipython'
-    home_dir = get_home_dir()
-    ipdir = os.path.abspath(os.environ.get('IPYTHONDIR',
-                                           os.path.join(home_dir,ipdir_def)))
-    return ipdir
-
 def import_item(key):
     """
     Import and return bar given the string foo.bar.
     """
     package = '.'.join(key.split('.')[0:-1])
     obj = key.split('.')[-1]
     execString = 'from %s import %s' % (package, obj)
     exec execString
     exec 'temp = %s' % obj 
     return temp

IPython/demo.py

@@ -1,526 +1,526
 """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.
 
 
 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.
 
 
 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> ############################
 """
 
 #*****************************************************************************
 #     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.
 #
 #*****************************************************************************
 
 import exceptions
 import os
 import re
 import shlex
 import sys
 
 from IPython.PyColorize import Parser
 from IPython.genutils import marquee, file_read, file_readlines
 
 __all__ = ['Demo','IPythonDemo','LineDemo','IPythonLineDemo','DemoError']
 
 class DemoError(exceptions.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_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,fname,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:
         
           - fname = filename.
 
         Optional inputs:
 
           - 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.
           """
         
         self.fname    = fname
         self.sys_argv = [fname] + shlex.split(arg_str)
         self.auto_all = auto_all
         
         # 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.
         self.ip_ns       = __IPYTHON__.user_ns
         self.ip_colorize = __IPYTHON__.pycolorize
         self.ip_showtb   = __IPYTHON__.showtraceback
         self.ip_runlines = __IPYTHON__.runlines
         self.shell       = __IPYTHON__
 
         # load user data and initialize data structures
         self.reload()
 
     def reload(self):
         """Reload source from disk and initialize state."""
         # read data and parse into blocks
         self.src     = file_read(self.fname)
         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 reset() if you want to rerun it.'
                 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.fname,index,self.nblocks-index-1))
         sys.stdout.write(self.src_blocks_colored[index])
         sys.stdout.flush()
 
     def show_all(self):
         """Show entire demo on screen, block by block"""
 
         fname = self.fname
         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)' %
                               (fname,index,nblocks-index-1))
             else:
                 print marquee('<%s> block # %s (%s remaining)' %
                               (fname,index,nblocks-index-1))
             print block,
         sys.stdout.flush()
 
     def runlines(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))
             else:
                 self.pre_cmd()
                 self.show(index)
                 if self.auto_all or self._auto[index]:
                     print marquee('output:')
                 else:
                     print marquee('Press <q> to quit, <Enter> to execute...'),
                     ans = raw_input().strip()
                     if ans:
                         print marquee('Block NOT executed')
                         return
             try:
                 save_argv = sys.argv
                 sys.argv = self.sys_argv
                 self.runlines(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 prints if empty marquees are used
                 print
                 print mq1
                 print self.marquee('Use reset() if you want to rerun it.')
             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 runlines(self,source):
         """Execute a string with one or more lines of code"""
 
         self.shell.runlines(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."""
     
     def reload(self):
         """Reload source from disk and initialize state."""
         # read data and parse into blocks
         src_b           = [l for l in file_readlines(self.fname) if l.strip()]
         nblocks         = len(src_b)
         self.src        = os.linesep.join(file_readlines(self.fname))
         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."""
         os.system('clear')
 
 
 class ClearDemo(ClearMixin,Demo):
     pass
 
 
 class ClearIPDemo(ClearMixin,IPythonDemo):
     pass

IPython/frontend/_process/killableprocess.py

@@ -1,168 +1,179
 # Addapted from killableprocess.py.  
 #______________________________________________________________________________
 #
 # killableprocess - subprocesses which can be reliably killed
 #
 # Parts of this module are copied from the subprocess.py file contained
 # in the Python distribution.
 #
 # Copyright (c) 2003-2004 by Peter Astrand <[e-mail]>
 #
 # Additions and modifications written by Benjamin Smedberg
 # <[e-mail]> are Copyright (c) 2006 by the Mozilla Foundation
 # <http://www.mozilla.org/>
 #
 # By obtaining, using, and/or copying this software and/or its
 # associated documentation, you agree that you have read, understood,
 # and will comply with the following terms and conditions:
 #
 # Permission to use, copy, modify, and distribute this software and
 # its associated documentation for any purpose and without fee is
 # hereby granted, provided that the above copyright notice appears in
 # all copies, and that both that copyright notice and this permission
 # notice appear in supporting documentation, and that the name of the
 # author not be used in advertising or publicity pertaining to
 # distribution of the software without specific, written prior
 # permission.
 #
 # THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 # INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
 # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 # CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
 # OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 # WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 r"""killableprocess - Subprocesses which can be reliably killed
 
 This module is a subclass of the builtin "subprocess" module. It allows
 processes that launch subprocesses to be reliably killed on Windows (via the Popen.kill() method.
 
 It also adds a timeout argument to Wait() for a limited period of time before
 forcefully killing the process.
 
 Note: On Windows, this module requires Windows 2000 or higher (no support for
 Windows 95, 98, or NT 4.0). It also requires ctypes, which is bundled with
 Python 2.5+ or available from http://python.net/crew/theller/ctypes/
 """
 
 import subprocess
 from subprocess import PIPE
 import sys
 import os
-import time
 import types
 
 try:
     from subprocess import CalledProcessError
 except ImportError:
     # Python 2.4 doesn't implement CalledProcessError
     class CalledProcessError(Exception):
         """This exception is raised when a process run by check_call() returns
         a non-zero exit status. The exit status will be stored in the
         returncode attribute."""
         def __init__(self, returncode, cmd):
             self.returncode = returncode
             self.cmd = cmd
         def __str__(self):
             return "Command '%s' returned non-zero exit status %d" % (self.cmd, self.returncode)
 
 mswindows = (sys.platform == "win32")
 
+skip = False
+
 if mswindows:
-    import winprocess
+    import platform
+    if platform.uname()[3] == '' or platform.uname()[3] > '6.0.6000':
+        # Killable process does not work under vista when starting for
+        # something else than cmd.
+        skip = True
+    else:
+        import winprocess
 else:
     import signal
 
 if not mswindows:
     def DoNothing(*args):
         pass
 
-class Popen(subprocess.Popen):
+
+if skip:
+ Popen = subprocess.Popen
+else:
+ class Popen(subprocess.Popen):
     if not mswindows:
         # Override __init__ to set a preexec_fn
         def __init__(self, *args, **kwargs):
             if len(args) >= 7:
                 raise Exception("Arguments preexec_fn and after must be passed by keyword.")
 
             real_preexec_fn = kwargs.pop("preexec_fn", None)
             def setpgid_preexec_fn():
                 os.setpgid(0, 0)
                 if real_preexec_fn:
                     apply(real_preexec_fn)
 
             kwargs['preexec_fn'] = setpgid_preexec_fn
 
             subprocess.Popen.__init__(self, *args, **kwargs)
 
     if mswindows:
         def _execute_child(self, args, executable, preexec_fn, close_fds,
                            cwd, env, universal_newlines, startupinfo,
                            creationflags, shell,
                            p2cread, p2cwrite,
                            c2pread, c2pwrite,
                            errread, errwrite):
             if not isinstance(args, types.StringTypes):
                 args = subprocess.list2cmdline(args)
 
             if startupinfo is None:
                 startupinfo = winprocess.STARTUPINFO()
             
             if None not in (p2cread, c2pwrite, errwrite):
                 startupinfo.dwFlags |= winprocess.STARTF_USESTDHANDLES
                 
                 startupinfo.hStdInput = int(p2cread)
                 startupinfo.hStdOutput = int(c2pwrite)
                 startupinfo.hStdError = int(errwrite)
             if shell:
                 startupinfo.dwFlags |= winprocess.STARTF_USESHOWWINDOW
                 startupinfo.wShowWindow = winprocess.SW_HIDE
                 comspec = os.environ.get("COMSPEC", "cmd.exe")
                 args = comspec + " /c " + args
 
             # We create a new job for this process, so that we can kill
             # the process and any sub-processes 
             self._job = winprocess.CreateJobObject()
 
             creationflags |= winprocess.CREATE_SUSPENDED
             creationflags |= winprocess.CREATE_UNICODE_ENVIRONMENT
 
             hp, ht, pid, tid = winprocess.CreateProcess(
                 executable, args,
                 None, None, # No special security
                 1, # Must inherit handles!
                 creationflags,
                 winprocess.EnvironmentBlock(env),
                 cwd, startupinfo)
             
             self._child_created = True
             self._handle = hp
             self._thread = ht
             self.pid = pid
 
             winprocess.AssignProcessToJobObject(self._job, hp)
             winprocess.ResumeThread(ht)
 
             if p2cread is not None:
                 p2cread.Close()
             if c2pwrite is not None:
                 c2pwrite.Close()
             if errwrite is not None:
                 errwrite.Close()
 
     def kill(self, group=True):
         """Kill the process. If group=True, all sub-processes will also be killed."""
         if mswindows:
             if group:
                 winprocess.TerminateJobObject(self._job, 127)
             else:
                 winprocess.TerminateProcess(self._handle, 127)
             self.returncode = 127    
         else:
             if group:
                 os.killpg(self.pid, signal.SIGKILL)
             else:
                 os.kill(self.pid, signal.SIGKILL)
             self.returncode = -9
 
 

IPython/frontend/_process/pipedprocess.py

@@ -1,74 +1,74
 # encoding: utf-8
 """
 Object for encapsulating process execution by using callbacks for stdout, 
 stderr and stdin.
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 from killableprocess import Popen, PIPE
 from threading import Thread
 from time import sleep
 import os
 
 class PipedProcess(Thread):
     """ Class that encapsulates process execution by using callbacks for
         stdout, stderr and stdin, and providing a reliable way of
         killing it.
     """
 
     def __init__(self, command_string, out_callback, 
                         end_callback=None,):
         """ command_string: the command line executed to start the
         process. 
 
         out_callback: the python callable called on stdout/stderr.
 
         end_callback: an optional callable called when the process
         finishes.
 
         These callbacks are called from a different thread as the
         thread from which is started.
         """
         self.command_string = command_string
         self.out_callback = out_callback
         self.end_callback = end_callback
         Thread.__init__(self)
     
 
     def run(self):
         """ Start the process and hook up the callbacks.
         """
         env = os.environ
         env['TERM'] = 'xterm'
-        process = Popen((self.command_string + ' 2>&1', ), shell=True,
+        process = Popen(self.command_string + ' 2>&1', shell=True,
                                 env=env,
                                 universal_newlines=True,
                                 stdout=PIPE, stdin=PIPE, )
         self.process = process
         while True:
             out_char = process.stdout.read(1)
             if out_char == '':
                 if process.poll() is not None:
                     # The process has finished
                     break
                 else:
                     # The process is not giving any interesting
                     # output. No use polling it immediatly.
                     sleep(0.1)
             else:
                 self.out_callback(out_char)
 
         if self.end_callback is not None:
             self.end_callback()
     
 

IPython/frontend/asyncfrontendbase.py

@@ -1,92 +1,76
 """
 Base front end class for all async frontends.
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 uuid
+from IPython.external import guid
 
-try:
-    from zope.interface import Interface, Attribute, implements, classProvides
-except ImportError, e:
-    e.message = """%s
-________________________________________________________________________________
-zope.interface is required to run asynchronous frontends.""" % e.message
-    e.args = (e.message, ) + e.args[1:]
 
-from frontendbase import FrontEndBase, IFrontEnd, IFrontEndFactory
-
-from IPython.kernel.engineservice import IEngineCore
+from zope.interface import Interface, Attribute, implements, classProvides
+from twisted.python.failure import Failure
+from IPython.frontend.frontendbase import FrontEndBase, IFrontEnd, IFrontEndFactory
 from IPython.kernel.core.history import FrontEndHistory
-
-try:
-    from twisted.python.failure import Failure
-except ImportError, e:
-    e.message = """%s
-________________________________________________________________________________
-twisted is required to run asynchronous frontends.""" % e.message
-    e.args = (e.message, ) + e.args[1:]
-
-
+from IPython.kernel.engineservice import IEngineCore
 
 
 class AsyncFrontEndBase(FrontEndBase):
     """
     Overrides FrontEndBase to wrap execute in a deferred result.
     All callbacks are made as callbacks on the deferred result.
     """
     
     implements(IFrontEnd)
     classProvides(IFrontEndFactory)
     
     def __init__(self, engine=None, history=None):
         assert(engine==None or IEngineCore.providedBy(engine))
         self.engine = IEngineCore(engine)
         if history is None:
                 self.history = FrontEndHistory(input_cache=[''])
         else:
             self.history = history
     
     
     def execute(self, block, blockID=None):
         """Execute the block and return the deferred result.
         
         Parameters:
             block : {str, AST}
             blockID : any
                 Caller may provide an ID to identify this block. 
                 result['blockID'] := blockID
         
         Result:
             Deferred result of self.interpreter.execute
         """
         
         if(not self.is_complete(block)):
             return Failure(Exception("Block is not compilable"))
         
         if(blockID == None):
-            blockID = uuid.uuid4() #random UUID
+            blockID = guid.generate() 
         
         d = self.engine.execute(block)
         d.addCallback(self._add_history, block=block)
         d.addCallbacks(self._add_block_id_for_result,
                 errback=self._add_block_id_for_failure,
                 callbackArgs=(blockID,),
                 errbackArgs=(blockID,))
         d.addBoth(self.update_cell_prompt, blockID=blockID)
         d.addCallbacks(self.render_result, 
             errback=self.render_error)
         
         return d
     
 

IPython/frontend/cocoa/cocoa_frontend.py

@@ -1,560 +1,560
 # encoding: utf-8
 # -*- test-case-name: IPython.frontend.cocoa.tests.test_cocoa_frontend -*-
 
 """PyObjC classes to provide a Cocoa frontend to the 
 IPython.kernel.engineservice.IEngineBase.
 
 To add an IPython interpreter to a cocoa app, instantiate an 
 IPythonCocoaController in a XIB and connect its textView outlet to an
 NSTextView instance in your UI. That's it.
 
 Author: Barry Wark
 """
 
 __docformat__ = "restructuredtext en"
 
 #-----------------------------------------------------------------------------
 #       Copyright (C) 2008  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 sys
 import objc
-import uuid
+from IPython.external import guid
 
 from Foundation import NSObject, NSMutableArray, NSMutableDictionary,\
                         NSLog, NSNotificationCenter, NSMakeRange,\
                         NSLocalizedString, NSIntersectionRange,\
                         NSString, NSAutoreleasePool
                         
 from AppKit import NSApplicationWillTerminateNotification, NSBeep,\
                     NSTextView, NSRulerView, NSVerticalRuler
 
 from pprint import saferepr
 
 import IPython
 from IPython.kernel.engineservice import ThreadedEngineService
 from IPython.frontend.asyncfrontendbase import AsyncFrontEndBase
 
 from twisted.internet.threads import blockingCallFromThread
 from twisted.python.failure import Failure
 
 #-----------------------------------------------------------------------------
 # Classes to implement the Cocoa frontend
 #-----------------------------------------------------------------------------
 
 # TODO: 
 #   1. use MultiEngineClient and out-of-process engine rather than 
 #       ThreadedEngineService?
 #   2. integrate Xgrid launching of engines
         
 class AutoreleasePoolWrappedThreadedEngineService(ThreadedEngineService):
     """Wrap all blocks in an NSAutoreleasePool"""
     
     def wrapped_execute(self, msg, lines):
         """wrapped_execute"""
         try:
             p = NSAutoreleasePool.alloc().init()
             result = super(AutoreleasePoolWrappedThreadedEngineService,
                             self).wrapped_execute(msg, lines)
         finally:
             p.drain()
         
         return result
     
 
 
 class Cell(NSObject):
     """
     Representation of the prompts, input and output of a cell in the
     frontend
     """
     
     blockNumber = objc.ivar().unsigned_long()
     blockID = objc.ivar()
     inputBlock = objc.ivar()
     output = objc.ivar()
      
 
    
 class CellBlock(object):
     """
     Storage for information about text ranges relating to a single cell
     """
 
         
     def __init__(self, inputPromptRange, inputRange=None, outputPromptRange=None,
                 outputRange=None):
         super(CellBlock, self).__init__()
         self.inputPromptRange = inputPromptRange
         self.inputRange = inputRange
         self.outputPromptRange = outputPromptRange
         self.outputRange = outputRange
     
     def update_ranges_for_insertion(self, text, textRange):
         """Update ranges for text insertion at textRange"""
         
         for r in [self.inputPromptRange,self.inputRange,
                     self.outputPromptRange, self.outputRange]:
             if(r == None):
                 continue
             intersection = NSIntersectionRange(r,textRange)
             if(intersection.length == 0): #ranges don't intersect
                 if r.location >= textRange.location:
                     r.location += len(text)
             else: #ranges intersect
                 if(r.location > textRange.location):
                     offset = len(text) - intersection.length
                     r.length -= offset
                     r.location += offset
                 elif(r.location == textRange.location):
                     r.length += len(text) - intersection.length
                 else:
                     r.length -= intersection.length
     
     
     def update_ranges_for_deletion(self, textRange):
         """Update ranges for text deletion at textRange"""
         
         for r in [self.inputPromptRange,self.inputRange,
                     self.outputPromptRange, self.outputRange]:
             if(r==None):
                 continue
             intersection = NSIntersectionRange(r, textRange)
             if(intersection.length == 0): #ranges don't intersect
                 if r.location >= textRange.location:
                     r.location -= textRange.length
             else: #ranges intersect
                 if(r.location > textRange.location):
                     offset = intersection.length
                     r.length -= offset
                     r.location += offset
                 elif(r.location == textRange.location):
                     r.length += intersection.length
                 else:
                     r.length -= intersection.length
     
     def __repr__(self):
         return 'CellBlock('+ str((self.inputPromptRange,
                                 self.inputRange,
                                 self.outputPromptRange,
                                 self.outputRange)) + ')'
     
 
 
         
 class IPythonCocoaController(NSObject, AsyncFrontEndBase):
     userNS = objc.ivar() #mirror of engine.user_ns (key=>str(value))
     waitingForEngine = objc.ivar().bool()
     textView = objc.IBOutlet()
     
     def init(self):
         self = super(IPythonCocoaController, self).init()
         AsyncFrontEndBase.__init__(self,
                     engine=AutoreleasePoolWrappedThreadedEngineService())
         if(self != None):
             self._common_init()
         
         return self
     
     def _common_init(self):
         """_common_init"""
         
         self.userNS = NSMutableDictionary.dictionary()
         self.waitingForEngine = False
         
         self.lines = {}
         self.tabSpaces = 4
         self.tabUsesSpaces = True
         self.currentBlockID = self.next_block_ID()
         self.blockRanges = {} # blockID=>CellBlock
     
     
     def awakeFromNib(self):
         """awakeFromNib"""
         
         self._common_init()
         
         # Start the IPython engine
         self.engine.startService()
         NSLog('IPython engine started')
         
         # Register for app termination
         nc = NSNotificationCenter.defaultCenter()
         nc.addObserver_selector_name_object_(
                                     self,
                                     'appWillTerminate:',
                                     NSApplicationWillTerminateNotification,
                                     None)
         
         self.textView.setDelegate_(self)
         self.textView.enclosingScrollView().setHasVerticalRuler_(True)
         r = NSRulerView.alloc().initWithScrollView_orientation_(
                                         self.textView.enclosingScrollView(),
                                         NSVerticalRuler)
         self.verticalRulerView = r
         self.verticalRulerView.setClientView_(self.textView)
         self._start_cli_banner()
         self.start_new_block()
     
     
     def appWillTerminate_(self, notification):
         """appWillTerminate"""
         
         self.engine.stopService()
     
     
     def complete(self, token):
         """Complete token in engine's user_ns
         
         Parameters
         ----------
         token : string
         
         Result
         ------
         Deferred result of 
         IPython.kernel.engineservice.IEngineBase.complete
         """
         
         return self.engine.complete(token)
     
     
     def execute(self, block, blockID=None):
         self.waitingForEngine = True
         self.willChangeValueForKey_('commandHistory')
         d = super(IPythonCocoaController, self).execute(block,
                                                         blockID)
         d.addBoth(self._engine_done)
         d.addCallback(self._update_user_ns)
         
         return d
     
     
     def push_(self, namespace):
         """Push dictionary of key=>values to python namespace"""
         
         self.waitingForEngine = True
         self.willChangeValueForKey_('commandHistory')
         d = self.engine.push(namespace)
         d.addBoth(self._engine_done)
         d.addCallback(self._update_user_ns)
     
     
     def pull_(self, keys):
         """Pull keys from python namespace"""
         
         self.waitingForEngine = True
         result = blockingCallFromThread(self.engine.pull, keys)
         self.waitingForEngine = False
     
     @objc.signature('v@:@I')
     def executeFileAtPath_encoding_(self, path, encoding):
         """Execute file at path in an empty namespace. Update the engine
         user_ns with the resulting locals."""
         
         lines,err = NSString.stringWithContentsOfFile_encoding_error_(
             path,
             encoding,
             None)
         self.engine.execute(lines)
     
     
     def _engine_done(self, x):
         self.waitingForEngine = False
         self.didChangeValueForKey_('commandHistory')
         return x
     
     def _update_user_ns(self, result):
         """Update self.userNS from self.engine's namespace"""
         d = self.engine.keys()
         d.addCallback(self._get_engine_namespace_values_for_keys)
         
         return result
     
     
     def _get_engine_namespace_values_for_keys(self, keys):
         d = self.engine.pull(keys)
         d.addCallback(self._store_engine_namespace_values, keys=keys)
     
     
     def _store_engine_namespace_values(self, values, keys=[]):
         assert(len(values) == len(keys))
         self.willChangeValueForKey_('userNS')
         for (k,v) in zip(keys,values):
             self.userNS[k] = saferepr(v)
         self.didChangeValueForKey_('userNS')
     
     
     def update_cell_prompt(self, result, blockID=None):
         print self.blockRanges
         if(isinstance(result, Failure)):
             prompt = self.input_prompt()
             
         else:
             prompt = self.input_prompt(number=result['number'])
         
         r = self.blockRanges[blockID].inputPromptRange
         self.insert_text(prompt,
                 textRange=r,
                 scrollToVisible=False
                 )
         
         return result
     
     
     def render_result(self, result):
         blockID = result['blockID']
         inputRange = self.blockRanges[blockID].inputRange
         del self.blockRanges[blockID]
         
         #print inputRange,self.current_block_range()
         self.insert_text('\n' +
                 self.output_prompt(number=result['number']) +
                 result.get('display',{}).get('pprint','') +
                 '\n\n',
                 textRange=NSMakeRange(inputRange.location+inputRange.length,
                                     0))
         return result
     
         
     def render_error(self, failure):
         print failure
         blockID = failure.blockID
         inputRange = self.blockRanges[blockID].inputRange
         self.insert_text('\n' +
                         self.output_prompt() +
                         '\n' +
                         failure.getErrorMessage() +
                         '\n\n',
                         textRange=NSMakeRange(inputRange.location +
                                                 inputRange.length,
                                                 0))
         self.start_new_block()
         return failure
     
     
     def _start_cli_banner(self):
         """Print banner"""
         
         banner = """IPython1 %s -- An enhanced Interactive Python.""" % \
                     IPython.__version__
         
         self.insert_text(banner + '\n\n')
     
     
     def start_new_block(self):
         """"""
         
         self.currentBlockID = self.next_block_ID()
         self.blockRanges[self.currentBlockID] = self.new_cell_block()
         self.insert_text(self.input_prompt(), 
             textRange=self.current_block_range().inputPromptRange)
     
     
     
     def next_block_ID(self):
         
-        return uuid.uuid4()
+        return guid.generate() 
     
     def new_cell_block(self):
         """A new CellBlock at the end of self.textView.textStorage()"""
         
         return CellBlock(NSMakeRange(self.textView.textStorage().length(), 
                                     0), #len(self.input_prompt())),
                         NSMakeRange(self.textView.textStorage().length(),# + len(self.input_prompt()),
                                     0))
     
     
     def current_block_range(self):
         return self.blockRanges.get(self.currentBlockID, 
                         self.new_cell_block())
     
     def current_block(self):
         """The current block's text"""
         
         return self.text_for_range(self.current_block_range().inputRange)
     
     def text_for_range(self, textRange):
         """text_for_range"""
         
         ts = self.textView.textStorage()
         return ts.string().substringWithRange_(textRange)
     
     def current_line(self):
         block = self.text_for_range(self.current_block_range().inputRange)
         block = block.split('\n')
         return block[-1]
     
     
     def insert_text(self, string=None, textRange=None, scrollToVisible=True):
         """Insert text into textView at textRange, updating blockRanges 
         as necessary
         """
         if(textRange == None):
             #range for end of text
             textRange = NSMakeRange(self.textView.textStorage().length(), 0) 
         
         
         self.textView.replaceCharactersInRange_withString_(
             textRange, string)
             
         for r in self.blockRanges.itervalues():
             r.update_ranges_for_insertion(string, textRange)
         
         self.textView.setSelectedRange_(textRange)
         if(scrollToVisible):
             self.textView.scrollRangeToVisible_(textRange)
     
     
     
     def replace_current_block_with_string(self, textView, string):
         textView.replaceCharactersInRange_withString_(
                                     self.current_block_range().inputRange,
                                     string)
         self.current_block_range().inputRange.length = len(string)
         r = NSMakeRange(textView.textStorage().length(), 0)
         textView.scrollRangeToVisible_(r)
         textView.setSelectedRange_(r)
     
     
     def current_indent_string(self):
         """returns string for indent or None if no indent"""
         
         return self._indent_for_block(self.current_block())
     
     
     def _indent_for_block(self, block):
         lines = block.split('\n')
         if(len(lines) > 1):
             currentIndent = len(lines[-1]) - len(lines[-1].lstrip())
             if(currentIndent == 0):
                 currentIndent = self.tabSpaces
         
             if(self.tabUsesSpaces):
                 result = ' ' * currentIndent
             else:
                 result = '\t' * (currentIndent/self.tabSpaces)
         else:
             result = None
         
         return result
     
     
     # NSTextView delegate methods...
     def textView_doCommandBySelector_(self, textView, selector):
         assert(textView == self.textView)
         NSLog("textView_doCommandBySelector_: "+selector)
         
         
         if(selector == 'insertNewline:'):
             indent = self.current_indent_string()
             if(indent):
                 line = indent + self.current_line()
             else:
                 line = self.current_line()
             
             if(self.is_complete(self.current_block())):
                 self.execute(self.current_block(),
                                 blockID=self.currentBlockID)
                 self.start_new_block()
                 
                 return True
             
             return False
         
         elif(selector == 'moveUp:'):
             prevBlock = self.get_history_previous(self.current_block())
             if(prevBlock != None):
                 self.replace_current_block_with_string(textView, prevBlock)
             else:
                 NSBeep()
             return True
         
         elif(selector == 'moveDown:'):
             nextBlock = self.get_history_next()
             if(nextBlock != None):
                 self.replace_current_block_with_string(textView, nextBlock)
             else:
                 NSBeep()
             return True
         
         elif(selector == 'moveToBeginningOfParagraph:'):
             textView.setSelectedRange_(NSMakeRange(
                             self.current_block_range().inputRange.location, 
                             0))
             return True
         elif(selector == 'moveToEndOfParagraph:'):
             textView.setSelectedRange_(NSMakeRange(
                             self.current_block_range().inputRange.location + \
                             self.current_block_range().inputRange.length, 0))
             return True
         elif(selector == 'deleteToEndOfParagraph:'):
             if(textView.selectedRange().location <= \
                 self.current_block_range().location):
                 raise NotImplemented()
             
             return False # don't actually handle the delete
         
         elif(selector == 'insertTab:'):
             if(len(self.current_line().strip()) == 0): #only white space
                 return False
             else:
                 self.textView.complete_(self)
                 return True
         
         elif(selector == 'deleteBackward:'):
             #if we're at the beginning of the current block, ignore
             if(textView.selectedRange().location == \
                 self.current_block_range().inputRange.location):
                 return True
             else:
                 for r in self.blockRanges.itervalues():
                     deleteRange = textView.selectedRange
                     if(deleteRange.length == 0):
                         deleteRange.location -= 1
                         deleteRange.length = 1
                     r.update_ranges_for_deletion(deleteRange)
                 return False
         return False
     
     
     def textView_shouldChangeTextInRanges_replacementStrings_(self, 
         textView, ranges, replacementStrings):
         """
         Delegate method for NSTextView.
         
         Refuse change text in ranges not at end, but make those changes at 
         end.
         """
         
         assert(len(ranges) == len(replacementStrings))
         allow = True
         for r,s in zip(ranges, replacementStrings):
             r = r.rangeValue()
             if(textView.textStorage().length() > 0 and
                 r.location < self.current_block_range().inputRange.location):
                 self.insert_text(s)
                 allow = False
         
         return allow
     
     def textView_completions_forPartialWordRange_indexOfSelectedItem_(self, 
         textView, words, charRange, index):
         try:
             ts = textView.textStorage()
             token = ts.string().substringWithRange_(charRange)
             completions = blockingCallFromThread(self.complete, token)
         except:
             completions = objc.nil
             NSBeep()
         
         return (completions,0)
     
 

IPython/frontend/cocoa/tests/test_cocoa_frontend.py

@@ -1,91 +1,94
 # encoding: utf-8
 """This file contains unittests for the 
 IPython.frontend.cocoa.cocoa_frontend module.
 """
 __docformat__ = "restructuredtext en"
                                                                             
 #---------------------------------------------------------------------------
 #       Copyright (C) 2005  The IPython Development Team    
 #                                                                           
 #  Distributed under the terms of the BSD License.  The full license is in  
 #  the file COPYING, distributed as part of this software.                  
 #---------------------------------------------------------------------------
                                                                             
 #---------------------------------------------------------------------------
 # Imports                                                                   
 #---------------------------------------------------------------------------
-from IPython.kernel.core.interpreter import Interpreter                     
-import IPython.kernel.engineservice as es
-from IPython.testing.util import DeferredTestCase
-from twisted.internet.defer import succeed
-from IPython.frontend.cocoa.cocoa_frontend import IPythonCocoaController
-                                                    
-from Foundation import NSMakeRect
-from AppKit import NSTextView, NSScrollView                                                
+
+try:
+    from IPython.kernel.core.interpreter import Interpreter
+    import IPython.kernel.engineservice as es
+    from IPython.testing.util import DeferredTestCase
+    from twisted.internet.defer import succeed
+    from IPython.frontend.cocoa.cocoa_frontend import IPythonCocoaController                                                    
+    from Foundation import NSMakeRect
+    from AppKit import NSTextView, NSScrollView                                                
+except ImportError:
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted, Foolscap and PyObjC")
 
 class TestIPythonCocoaControler(DeferredTestCase):
     """Tests for IPythonCocoaController"""
-    
+   
     def setUp(self):
         self.controller = IPythonCocoaController.alloc().init()
         self.engine = es.EngineService()
         self.engine.startService()
-    
-    
+   
     def tearDown(self):
         self.controller = None
         self.engine.stopService()
-    
+   
     def testControllerExecutesCode(self):
         code ="""5+5"""
         expected = Interpreter().execute(code)
         del expected['number']
         def removeNumberAndID(result):
             del result['number']
             del result['id']
             return result
         self.assertDeferredEquals(
             self.controller.execute(code).addCallback(removeNumberAndID), 
             expected)
-    
+   
     def testControllerMirrorsUserNSWithValuesAsStrings(self):
         code = """userns1=1;userns2=2"""
         def testControllerUserNS(result):
             self.assertEquals(self.controller.userNS['userns1'], 1)
             self.assertEquals(self.controller.userNS['userns2'], 2)
-        
+       
         self.controller.execute(code).addCallback(testControllerUserNS)
-    
-    
+   
+   
     def testControllerInstantiatesIEngine(self):
         self.assert_(es.IEngineBase.providedBy(self.controller.engine))
-    
+   
     def testControllerCompletesToken(self):
         code = """longNameVariable=10"""
         def testCompletes(result):
             self.assert_("longNameVariable" in result)
-        
+       
         def testCompleteToken(result):
             self.controller.complete("longNa").addCallback(testCompletes)
-        
+       
         self.controller.execute(code).addCallback(testCompletes)
-    
-    
+   
+   
     def testCurrentIndent(self):
         """test that current_indent_string returns current indent or None.
         Uses _indent_for_block for direct unit testing.
         """
-        
+       
         self.controller.tabUsesSpaces = True
         self.assert_(self.controller._indent_for_block("""a=3""") == None)
         self.assert_(self.controller._indent_for_block("") == None)
         block = """def test():\n    a=3"""
         self.assert_(self.controller._indent_for_block(block) == \
                     ' ' * self.controller.tabSpaces)
-        
+       
         block = """if(True):\n%sif(False):\n%spass""" % \
                     (' '*self.controller.tabSpaces,
                      2*' '*self.controller.tabSpaces)
         self.assert_(self.controller._indent_for_block(block) == \
                     2*(' '*self.controller.tabSpaces))
-    
+   

IPython/frontend/frontendbase.py

@@ -1,359 +1,343
 # encoding: utf-8
 # -*- test-case-name: IPython.frontend.tests.test_frontendbase -*-
 """
 frontendbase provides an interface and base class for GUI frontends for 
 IPython.kernel/IPython.kernel.core.
 
 Frontend implementations will likely want to subclass FrontEndBase. 
 
 Author: Barry Wark
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 string
-import uuid
-import _ast
+import codeop
+from IPython.external import guid
 
-from zopeinterface import Interface, Attribute, implements, classProvides
 
+from IPython.frontend.zopeinterface import (
+    Interface, 
+    Attribute, 
+)
 from IPython.kernel.core.history import FrontEndHistory
 from IPython.kernel.core.util import Bunch
-from IPython.kernel.engineservice import IEngineCore
 
 ##############################################################################
 # TEMPORARY!!! fake configuration, while we decide whether to use tconfig or
 # not
 
 rc = Bunch()
 rc.prompt_in1 = r'In [$number]:  '
 rc.prompt_in2 = r'...'
 rc.prompt_out = r'Out [$number]:  '
 
 ##############################################################################
 # Interface definitions
 ##############################################################################
 
 class IFrontEndFactory(Interface):
     """Factory interface for frontends."""
     
     def __call__(engine=None, history=None):
         """
         Parameters:
         interpreter : IPython.kernel.engineservice.IEngineCore
         """
         
         pass
 
 
 class IFrontEnd(Interface):
     """Interface for frontends. All methods return t.i.d.Deferred"""
     
     Attribute("input_prompt_template", "string.Template instance\
                 substituteable with execute result.")
     Attribute("output_prompt_template", "string.Template instance\
                 substituteable with execute result.")
     Attribute("continuation_prompt_template", "string.Template instance\
                 substituteable with execute result.")
     
     def update_cell_prompt(result, blockID=None):
         """Subclass may override to update the input prompt for a block. 
 
         In asynchronous frontends, this method will be called as a
         twisted.internet.defer.Deferred's callback/errback.
         Implementations should thus return result when finished.
         
         Result is a result dict in case of success, and a
         twisted.python.util.failure.Failure in case of an error
         """
         
         pass
     
     def render_result(result):
         """Render the result of an execute call. Implementors may choose the
          method of rendering.
         For example, a notebook-style frontend might render a Chaco plot 
         inline.
         
         Parameters:
             result : dict (result of IEngineBase.execute )
                 blockID = result['blockID']
         
         Result:
             Output of frontend rendering
         """
         
         pass
     
     def render_error(failure):
         """Subclasses must override to render the failure. 
         
         In asynchronous frontend, since this method will be called as a
         twisted.internet.defer.Deferred's callback. Implementations
         should thus return result when finished.
         
         blockID = failure.blockID
         """
         
         pass
     
     def input_prompt(number=''):
         """Returns the input prompt by subsituting into 
         self.input_prompt_template
         """
         pass
     
     def output_prompt(number=''):
         """Returns the output prompt by subsituting into 
         self.output_prompt_template
         """
         
         pass
     
     def continuation_prompt():
         """Returns the continuation prompt by subsituting into 
         self.continuation_prompt_template
         """
         
         pass
     
     def is_complete(block):
         """Returns True if block is complete, False otherwise."""
         
         pass
     
-    def compile_ast(block):
-        """Compiles block to an _ast.AST"""
-        
-        pass
-    
+   
     def get_history_previous(current_block):
         """Returns the block previous in  the history. Saves currentBlock if
         the history_cursor is currently at the end of the input history"""
         pass
     
     def get_history_next():
         """Returns the next block in the history."""
         
         pass
     
     def complete(self, line):
         """Returns the list of possible completions, and the completed
             line.
 
         The input argument is the full line to be completed. This method
         returns both the line completed as much as possible, and the list
         of further possible completions (full words).
         """
         pass
 
 
 ##############################################################################
 # Base class for all the frontends. 
 ##############################################################################
 
 class FrontEndBase(object):
     """
     FrontEndBase manages the state tasks for a CLI frontend:
         - Input and output history management
         - Input/continuation and output prompt generation
         
     Some issues (due to possibly unavailable engine):
         - How do we get the current cell number for the engine?
         - How do we handle completions?
     """
     
     history_cursor = 0
     
     input_prompt_template = string.Template(rc.prompt_in1)
     output_prompt_template = string.Template(rc.prompt_out)
     continuation_prompt_template = string.Template(rc.prompt_in2)
     
     def __init__(self, shell=None, history=None):
         self.shell = shell
         if history is None:
                 self.history = FrontEndHistory(input_cache=[''])
         else:
             self.history = history
         
     
     def input_prompt(self, number=''):
         """Returns the current input prompt
         
         It would be great to use ipython1.core.prompts.Prompt1 here
         """
         return self.input_prompt_template.safe_substitute({'number':number})
     
     
     def continuation_prompt(self):
         """Returns the current continuation prompt"""
         
         return self.continuation_prompt_template.safe_substitute()
     
     def output_prompt(self, number=''):
         """Returns the output prompt for result"""
         
         return self.output_prompt_template.safe_substitute({'number':number})
     
     
     def is_complete(self, block):
         """Determine if block is complete.
         
         Parameters
         block : string
         
         Result 
         True if block can be sent to the engine without compile errors.
         False otherwise.
         """
         
         try:
-            ast = self.compile_ast(block)
+            is_complete = codeop.compile_command(block.rstrip() + '\n\n',
+                            "<string>", "exec") 
         except:
             return False
         
         lines = block.split('\n')
-        return (len(lines)==1 or str(lines[-1])=='')
-    
-    
-    def compile_ast(self, block):
-        """Compile block to an AST
-        
-        Parameters:
-            block : str
-        
-        Result:
-            AST
-        
-        Throws:
-            Exception if block cannot be compiled
-        """
-        
-        return compile(block, "<string>", "exec", _ast.PyCF_ONLY_AST)
+        return ((is_complete is not None) 
+                    and (len(lines)==1 or str(lines[-1])==''))
     
     
     def execute(self, block, blockID=None):
         """Execute the block and return the result.
         
         Parameters:
             block : {str, AST}
             blockID : any
                 Caller may provide an ID to identify this block. 
                 result['blockID'] := blockID
         
         Result:
             Deferred result of self.interpreter.execute
         """
         
         if(not self.is_complete(block)):
             raise Exception("Block is not compilable")
         
         if(blockID == None):
-            blockID = uuid.uuid4() #random UUID
+            blockID = guid.generate()
         
         try:
             result = self.shell.execute(block)
         except Exception,e:
             e = self._add_block_id_for_failure(e, blockID=blockID)
             e = self.update_cell_prompt(e, blockID=blockID)
             e = self.render_error(e)
         else:
             result = self._add_block_id_for_result(result, blockID=blockID)
             result = self.update_cell_prompt(result, blockID=blockID)
             result = self.render_result(result)
         
         return result
     
     
     def _add_block_id_for_result(self, result, blockID):
         """Add the blockID to result or failure. Unfortunatley, we have to 
         treat failures differently than result dicts.
         """
         
         result['blockID'] = blockID
         
         return result
     
     def _add_block_id_for_failure(self, failure, blockID):
         """_add_block_id_for_failure"""
         failure.blockID = blockID
         return failure
     
     
     def _add_history(self, result, block=None):
         """Add block to the history"""
         
         assert(block != None)
         self.history.add_items([block])
         self.history_cursor += 1
         
         return result
     
     
     def get_history_previous(self, current_block):
         """ Returns previous history string and decrement history cursor.
         """
         command = self.history.get_history_item(self.history_cursor - 1)
         
         if command is not None:
             if(self.history_cursor+1 == len(self.history.input_cache)):
                 self.history.input_cache[self.history_cursor] = current_block
             self.history_cursor -= 1
         return command
     
     
     def get_history_next(self):
         """ Returns next history string and increment history cursor.
         """
         command = self.history.get_history_item(self.history_cursor+1)
         
         if command is not None:
             self.history_cursor += 1
         return command
     
     ###
     # Subclasses probably want to override these methods...
     ###
     
     def update_cell_prompt(self, result, blockID=None):
         """Subclass may override to update the input prompt for a block. 
 
         This method only really makes sens in asyncrhonous frontend.
         Since this method will be called as a 
         twisted.internet.defer.Deferred's callback, implementations should 
         return result when finished.
         """
         
         raise NotImplementedError
     
     
     def render_result(self, result):
         """Subclasses must override to render result. 
         
         In asynchronous frontends, this method will be called as a
         twisted.internet.defer.Deferred's callback. Implementations
         should thus return result when finished.
         """
         
         raise NotImplementedError
     
     
     def render_error(self, failure):
         """Subclasses must override to render the failure. 
         
         In asynchronous frontends, this method will be called as a
         twisted.internet.defer.Deferred's callback. Implementations
         should thus return result when finished.
         """
         
         raise NotImplementedError
 

IPython/frontend/linefrontendbase.py

@@ -1,294 +1,333
 """
 Base front end class for all line-oriented frontends, rather than
 block-oriented.
 
 Currently this focuses on synchronous frontends.
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 re
 
 import IPython
 import sys
+import codeop
+import traceback
 
 from frontendbase import FrontEndBase
 from IPython.kernel.core.interpreter import Interpreter
 
 def common_prefix(strings):
     """ Given a list of strings, return the common prefix between all
         these strings.
     """
     ref = strings[0]
     prefix = ''
     for size in range(len(ref)):
         test_prefix = ref[:size+1]
         for string in strings[1:]:
             if not string.startswith(test_prefix):
                 return prefix
         prefix = test_prefix
 
     return prefix
 
 #-------------------------------------------------------------------------------
 # Base class for the line-oriented front ends
 #-------------------------------------------------------------------------------
 class LineFrontEndBase(FrontEndBase):
     """ Concrete implementation of the FrontEndBase class. This is meant
     to be the base class behind all the frontend that are line-oriented,
     rather than block-oriented.
     """
     
     # We need to keep the prompt number, to be able to increment
     # it when there is an exception.
     prompt_number = 1
 
     # We keep a reference to the last result: it helps testing and
     # programatic control of the frontend. 
     last_result = dict(number=0)
 
     # The input buffer being edited
     input_buffer = ''
 
     # Set to true for debug output
     debug = False
 
     # A banner to print at startup
     banner = None
 
     #--------------------------------------------------------------------------
     # FrontEndBase interface
     #--------------------------------------------------------------------------
 
     def __init__(self, shell=None, history=None, banner=None, *args, **kwargs):
         if shell is None:
             shell = Interpreter()
         FrontEndBase.__init__(self, shell=shell, history=history)
 
         if banner is not None:
             self.banner = banner
+
+    def start(self):
+        """ Put the frontend in a state where it is ready for user
+            interaction.
+        """
         if self.banner is not None:
             self.write(self.banner, refresh=False)
 
         self.new_prompt(self.input_prompt_template.substitute(number=1))
 
 
     def complete(self, line):
         """Complete line in engine's user_ns
         
         Parameters
         ----------
         line : string
         
         Result
         ------
         The replacement for the line and the list of possible completions.
         """
         completions = self.shell.complete(line)
         complete_sep =  re.compile('[\s\{\}\[\]\(\)\=]')
         if completions:
             prefix = common_prefix(completions) 
             residual = complete_sep.split(line)[:-1]
             line = line[:-len(residual)] + prefix
         return line, completions 
  
 
     def render_result(self, result):
         """ Frontend-specific rendering of the result of a calculation
         that has been sent to an engine.
         """
         if 'stdout' in result and result['stdout']:
             self.write('\n' + result['stdout'])
         if 'display' in result and result['display']:
             self.write("%s%s\n" % ( 
                             self.output_prompt_template.substitute(
                                     number=result['number']),
                             result['display']['pprint']
                             ) )
        
 
     def render_error(self, failure):
         """ Frontend-specific rendering of error. 
         """
         self.write('\n\n'+str(failure)+'\n\n')
         return failure
 
 
     def is_complete(self, string):
         """ Check if a string forms a complete, executable set of
         commands.
 
         For the line-oriented frontend, multi-line code is not executed
         as soon as it is complete: the users has to enter two line
         returns.
         """
         if string in ('', '\n'):
             # Prefiltering, eg through ipython0, may return an empty
             # string although some operations have been accomplished. We
             # thus want to consider an empty string as a complete
             # statement.
             return True
         elif ( len(self.input_buffer.split('\n'))>2 
                         and not re.findall(r"\n[\t ]*\n[\t ]*$", string)):
             return False
         else:
-            # Add line returns here, to make sure that the statement is
-            # complete.
-            return FrontEndBase.is_complete(self, string.rstrip() + '\n\n')
+            self.capture_output()
+            try:
+                # Add line returns here, to make sure that the statement is
+                # complete.
+                is_complete = codeop.compile_command(string.rstrip() + '\n\n',
+                            "<string>", "exec")
+                self.release_output()
+            except Exception, e:
+                # XXX: Hack: return True so that the
+                # code gets executed and the error captured.
+                is_complete = True
+            return is_complete
 
 
     def write(self, string, refresh=True):
         """ Write some characters to the display.
 
             Subclass should overide this method.
 
             The refresh keyword argument is used in frontends with an
             event loop, to choose whether the write should trigget an UI
             refresh, and thus be syncrhonous, or not.
         """
         print >>sys.__stderr__, string
 
 
     def execute(self, python_string, raw_string=None):
         """ Stores the raw_string in the history, and sends the
         python string to the interpreter.
         """
         if raw_string is None:
             raw_string = python_string
         # Create a false result, in case there is an exception
         self.last_result = dict(number=self.prompt_number)
+
+        ## try:
+        ##     self.history.input_cache[-1] = raw_string.rstrip()
+        ##     result = self.shell.execute(python_string)
+        ##     self.last_result = result
+        ##     self.render_result(result)
+        ## except:
+        ##     self.show_traceback()
+        ## finally:
+        ##     self.after_execute()
+
         try:
-            self.history.input_cache[-1] = raw_string.rstrip()
-            result = self.shell.execute(python_string)
-            self.last_result = result
-            self.render_result(result)
-        except:
-            self.show_traceback()
+            try:
+                self.history.input_cache[-1] = raw_string.rstrip()
+                result = self.shell.execute(python_string)
+                self.last_result = result
+                self.render_result(result)
+            except:
+                self.show_traceback()
         finally:
             self.after_execute()
 
+
     #--------------------------------------------------------------------------
     # LineFrontEndBase interface
     #--------------------------------------------------------------------------
 
     def prefilter_input(self, string):
-        """ Priflter the input to turn it in valid python.
+        """ Prefilter the input to turn it in valid python.
         """
         string = string.replace('\r\n', '\n')
         string = string.replace('\t', 4*' ')
         # Clean the trailing whitespace
         string = '\n'.join(l.rstrip()  for l in string.split('\n'))
         return string
 
 
     def after_execute(self):
         """ All the operations required after an execution to put the
             terminal back in a shape where it is usable.
         """
         self.prompt_number += 1
         self.new_prompt(self.input_prompt_template.substitute(
                             number=(self.last_result['number'] + 1)))
         # Start a new empty history entry
         self._add_history(None, '')
         self.history_cursor = len(self.history.input_cache) - 1
 
 
     def complete_current_input(self):
         """ Do code completion on current line. 
         """
         if self.debug:
             print >>sys.__stdout__, "complete_current_input", 
         line = self.input_buffer
         new_line, completions = self.complete(line)
         if len(completions)>1:
-            self.write_completion(completions)
-        self.input_buffer = new_line
+            self.write_completion(completions, new_line=new_line)
+        elif not line == new_line:
+            self.input_buffer = new_line
         if self.debug:
+            print >>sys.__stdout__, 'line', line
+            print >>sys.__stdout__, 'new_line', new_line
             print >>sys.__stdout__, completions 
 
 
     def get_line_width(self):
         """ Return the width of the line in characters.
         """
         return 80
 
 
-    def write_completion(self, possibilities):
+    def write_completion(self, possibilities, new_line=None):
         """ Write the list of possible completions.
+
+            new_line is the completed input line that should be displayed
+            after the completion are writen. If None, the input_buffer
+            before the completion is used.
         """
-        current_buffer = self.input_buffer
+        if new_line is None:
+            new_line = self.input_buffer
         
         self.write('\n')
         max_len = len(max(possibilities, key=len)) + 1
         
         # Now we check how much symbol we can put on a line...
         chars_per_line = self.get_line_width()
         symbols_per_line = max(1, chars_per_line/max_len)
 
         pos = 1
         buf = []
         for symbol in possibilities:
             if pos < symbols_per_line:
                 buf.append(symbol.ljust(max_len))
                 pos += 1
             else:
                 buf.append(symbol.rstrip() + '\n')
                 pos = 1
         self.write(''.join(buf))
         self.new_prompt(self.input_prompt_template.substitute(
                             number=self.last_result['number'] + 1))
-        self.input_buffer = current_buffer
+        self.input_buffer = new_line
 
 
     def new_prompt(self, prompt):
         """ Prints a prompt and starts a new editing buffer. 
 
             Subclasses should use this method to make sure that the
             terminal is put in a state favorable for a new line
             input.
         """
         self.input_buffer = ''
         self.write(prompt)
 
 
     #--------------------------------------------------------------------------
     # Private API
     #--------------------------------------------------------------------------
  
     def _on_enter(self):
         """ Called when the return key is pressed in a line editing
             buffer.
         """
         current_buffer = self.input_buffer
         cleaned_buffer = self.prefilter_input(current_buffer)
         if self.is_complete(cleaned_buffer):
             self.execute(cleaned_buffer, raw_string=current_buffer)
         else:
             self.input_buffer += self._get_indent_string(
                                                 current_buffer[:-1])
+            if len(current_buffer.split('\n')) == 2:
+                self.input_buffer += '\t\t'
             if current_buffer[:-1].split('\n')[-1].rstrip().endswith(':'):
                 self.input_buffer += '\t'
 
 
     def _get_indent_string(self, string):
         """ Return the string of whitespace that prefixes a line. Used to
         add the right amount of indendation when creating a new line.
         """
         string = string.replace('\t', ' '*4)
         string = string.split('\n')[-1]
         indent_chars = len(string) - len(string.lstrip())
         indent_string = '\t'*(indent_chars // 4) + \
                             ' '*(indent_chars % 4)
 
         return indent_string
  
     

IPython/frontend/prefilterfrontend.py

@@ -1,223 +1,246
 """
 Frontend class that uses IPython0 to prefilter the inputs.
 
 Using the IPython0 mechanism gives us access to the magics.
 
 This is a transitory class, used here to do the transition between
 ipython0 and ipython1. This class is meant to be short-lived as more
 functionnality is abstracted out of ipython0 in reusable functions and
 is added on the interpreter. This class can be a used to guide this
 refactoring.
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 sys
 
 from linefrontendbase import LineFrontEndBase, common_prefix
+from frontendbase import FrontEndBase
 
 from IPython.ipmaker import make_IPython
 from IPython.ipapi import IPApi
 from IPython.kernel.core.redirector_output_trap import RedirectorOutputTrap
 
 from IPython.kernel.core.sync_traceback_trap import SyncTracebackTrap
 
 from IPython.genutils import Term
 import pydoc
 import os
+import sys
 
 
 def mk_system_call(system_call_function, command):
     """ given a os.system replacement, and a leading string command,
         returns a function that will execute the command with the given
         argument string.
     """
     def my_system_call(args):
         system_call_function("%s %s" % (command, args))
     return my_system_call
 
 #-------------------------------------------------------------------------------
 # Frontend class using ipython0 to do the prefiltering. 
 #-------------------------------------------------------------------------------
 class PrefilterFrontEnd(LineFrontEndBase):
     """ Class that uses ipython0 to do prefilter the input, do the
     completion and the magics.
 
     The core trick is to use an ipython0 instance to prefilter the
     input, and share the namespace between the interpreter instance used
     to execute the statements and the ipython0 used for code
     completion...
     """
+
+    debug = False
     
     def __init__(self, ipython0=None, *args, **kwargs):
         """ Parameters:
             -----------
 
             ipython0: an optional ipython0 instance to use for command
             prefiltering and completion.
         """
+        LineFrontEndBase.__init__(self, *args, **kwargs)
+        self.shell.output_trap = RedirectorOutputTrap(
+                            out_callback=self.write,
+                            err_callback=self.write,
+                                            )
+        self.shell.traceback_trap = SyncTracebackTrap(
+                        formatters=self.shell.traceback_trap.formatters,
+                            )
+
+        # Start the ipython0 instance:
         self.save_output_hooks()
         if ipython0 is None:
             # Instanciate an IPython0 interpreter to be able to use the
             # prefiltering.
             # XXX: argv=[] is a bit bold.
-            ipython0 = make_IPython(argv=[])
+            ipython0 = make_IPython(argv=[], 
+                                    user_ns=self.shell.user_ns,
+                                    user_global_ns=self.shell.user_global_ns)
         self.ipython0 = ipython0
         # Set the pager:
         self.ipython0.set_hook('show_in_pager', 
                     lambda s, string: self.write("\n" + string))
         self.ipython0.write = self.write
         self._ip = _ip = IPApi(self.ipython0)
         # Make sure the raw system call doesn't get called, as we don't
         # have a stdin accessible.
         self._ip.system = self.system_call
         # XXX: Muck around with magics so that they work better
         # in our environment
         self.ipython0.magic_ls = mk_system_call(self.system_call, 
                                                             'ls -CF')
         # And now clean up the mess created by ipython0
         self.release_output()
+
+
         if not 'banner' in kwargs and self.banner is None:
-            kwargs['banner'] = self.ipython0.BANNER + """
+            self.banner = self.ipython0.BANNER + """
 This is the wx frontend, by Gael Varoquaux. This is EXPERIMENTAL code."""
 
-        LineFrontEndBase.__init__(self, *args, **kwargs)
-        # XXX: Hack: mix the two namespaces
-        self.shell.user_ns.update(self.ipython0.user_ns)
-        self.ipython0.user_ns = self.shell.user_ns 
-        self.shell.user_global_ns.update(self.ipython0.user_global_ns)
-        self.ipython0.user_global_ns = self.shell.user_global_ns
-
-        self.shell.output_trap = RedirectorOutputTrap(
-                            out_callback=self.write,
-                            err_callback=self.write,
-                                            )
-        self.shell.traceback_trap = SyncTracebackTrap(
-                        formatters=self.shell.traceback_trap.formatters,
-                            )
+        self.start()
 
     #--------------------------------------------------------------------------
     # FrontEndBase interface 
     #--------------------------------------------------------------------------
 
     def show_traceback(self):
         """ Use ipython0 to capture the last traceback and display it.
         """
         self.capture_output()
-        self.ipython0.showtraceback()
+        self.ipython0.showtraceback(tb_offset=-1)
         self.release_output()
 
 
     def execute(self, python_string, raw_string=None):
         if self.debug:
             print 'Executing Python code:', repr(python_string)
         self.capture_output()
         LineFrontEndBase.execute(self, python_string,
                                     raw_string=raw_string)
         self.release_output()
 
 
     def save_output_hooks(self):
         """ Store all the output hooks we can think of, to be able to
         restore them. 
         
         We need to do this early, as starting the ipython0 instance will
         screw ouput hooks.
         """
         self.__old_cout_write = Term.cout.write
         self.__old_cerr_write = Term.cerr.write
         self.__old_stdout = sys.stdout
         self.__old_stderr= sys.stderr
         self.__old_help_output = pydoc.help.output
         self.__old_display_hook = sys.displayhook
 
 
     def capture_output(self):
         """ Capture all the output mechanisms we can think of.
         """
         self.save_output_hooks()
         Term.cout.write = self.write
         Term.cerr.write = self.write
         sys.stdout = Term.cout
         sys.stderr = Term.cerr
         pydoc.help.output = self.shell.output_trap.out
 
 
     def release_output(self):
         """ Release all the different captures we have made.
         """
         Term.cout.write = self.__old_cout_write
         Term.cerr.write = self.__old_cerr_write
         sys.stdout = self.__old_stdout
         sys.stderr = self.__old_stderr
         pydoc.help.output = self.__old_help_output 
         sys.displayhook = self.__old_display_hook 
 
 
     def complete(self, line):
+        # FIXME: This should be factored out in the linefrontendbase
+        # method.
         word = line.split('\n')[-1].split(' ')[-1]
         completions = self.ipython0.complete(word)
         # FIXME: The proper sort should be done in the complete method.
         key = lambda x: x.replace('_', '')
         completions.sort(key=key)
         if completions:
             prefix = common_prefix(completions) 
             line = line[:-len(word)] + prefix
         return line, completions 
  
     
     #--------------------------------------------------------------------------
     # LineFrontEndBase interface 
     #--------------------------------------------------------------------------
 
     def prefilter_input(self, input_string):
         """ Using IPython0 to prefilter the commands to turn them
         in executable statements that are valid Python strings.
         """
         input_string = LineFrontEndBase.prefilter_input(self, input_string)
         filtered_lines = []
         # The IPython0 prefilters sometime produce output. We need to
         # capture it.
         self.capture_output()
         self.last_result = dict(number=self.prompt_number)
+        
+        ## try:
+        ##     for line in input_string.split('\n'):
+        ##         filtered_lines.append(
+        ##                 self.ipython0.prefilter(line, False).rstrip())
+        ## except:
+        ##     # XXX: probably not the right thing to do.
+        ##     self.ipython0.showsyntaxerror()
+        ##     self.after_execute()
+        ## finally:
+        ##     self.release_output()
+
+
         try:
-            for line in input_string.split('\n'):
-                filtered_lines.append(
-                        self.ipython0.prefilter(line, False).rstrip())
-        except:
-            # XXX: probably not the right thing to do.
-            self.ipython0.showsyntaxerror()
-            self.after_execute()
+            try:
+                for line in input_string.split('\n'):
+                    filtered_lines.append(
+                            self.ipython0.prefilter(line, False).rstrip())
+            except:
+                # XXX: probably not the right thing to do.
+                self.ipython0.showsyntaxerror()
+                self.after_execute()
         finally:
             self.release_output()
 
+
+
         # Clean up the trailing whitespace, to avoid indentation errors
         filtered_string = '\n'.join(filtered_lines)
         return filtered_string
 
 
     #--------------------------------------------------------------------------
     # PrefilterFrontEnd interface 
     #--------------------------------------------------------------------------
  
     def system_call(self, command_string):
         """ Allows for frontend to define their own system call, to be
             able capture output and redirect input.
         """
         return os.system(command_string)
 
 
     def do_exit(self):
         """ Exit the shell, cleanup and save the history.
         """
         self.ipython0.atexit_operations()
 

IPython/frontend/tests/test_frontendbase.py

@@ -1,152 +1,32
 # encoding: utf-8
-
-"""This file contains unittests for the frontendbase module."""
+"""
+Test the basic functionality of frontendbase. 
+"""
 
 __docformat__ = "restructuredtext en"
 
-#---------------------------------------------------------------------------
-#  Copyright (C) 2008  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                                                                   
-#---------------------------------------------------------------------------
+#-------------------------------------------------------------------------------
+#  Copyright (C) 2008  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.
+#-------------------------------------------------------------------------------
 
-import unittest
-from IPython.frontend.asyncfrontendbase import AsyncFrontEndBase
-from IPython.frontend import frontendbase 
-from IPython.kernel.engineservice import EngineService
+from IPython.frontend.frontendbase import FrontEndBase
 
-class FrontEndCallbackChecker(AsyncFrontEndBase):
-    """FrontEndBase subclass for checking callbacks"""
-    def __init__(self, engine=None, history=None):
-        super(FrontEndCallbackChecker, self).__init__(engine=engine, 
-                                                    history=history)
-        self.updateCalled = False
-        self.renderResultCalled = False
-        self.renderErrorCalled = False
-    
-    def update_cell_prompt(self, result, blockID=None):
-        self.updateCalled = True
-        return result
-    
-    def render_result(self, result):
-        self.renderResultCalled = True
-        return result
-    
-    
-    def render_error(self, failure):
-        self.renderErrorCalled = True
-        return failure
-    
+def test_iscomplete():
+    """ Check that is_complete works. 
+    """
+    f = FrontEndBase()
+    assert f.is_complete('(a + a)')
+    assert not f.is_complete('(a + a')
+    assert f.is_complete('1')
+    assert not f.is_complete('1 + ')
+    assert not f.is_complete('1 + \n\n')
+    assert f.is_complete('if True:\n  print 1\n')
+    assert not f.is_complete('if True:\n  print 1')
+    assert f.is_complete('def f():\n  print 1\n')
 
+if __name__ == '__main__':
+    test_iscomplete()
 
-    
-class TestAsyncFrontendBase(unittest.TestCase):
-    def setUp(self):
-        """Setup the EngineService and FrontEndBase"""
-        
-        self.fb = FrontEndCallbackChecker(engine=EngineService())
-    
-    
-    def test_implements_IFrontEnd(self):
-        assert(frontendbase.IFrontEnd.implementedBy(
-                                    AsyncFrontEndBase))
-    
-    
-    def test_is_complete_returns_False_for_incomplete_block(self):
-        """"""
-        
-        block = """def test(a):"""
-        
-        assert(self.fb.is_complete(block) == False)
-    
-    def test_is_complete_returns_True_for_complete_block(self):
-        """"""
-        
-        block = """def test(a): pass"""
-            
-        assert(self.fb.is_complete(block))
-        
-        block = """a=3"""
-        
-        assert(self.fb.is_complete(block))
-    
-    
-    def test_blockID_added_to_result(self):
-        block = """3+3"""
-        
-        d = self.fb.execute(block, blockID='TEST_ID')
-        
-        d.addCallback(self.checkBlockID, expected='TEST_ID')
-    
-    def test_blockID_added_to_failure(self):
-        block = "raise Exception()"
-        
-        d = self.fb.execute(block,blockID='TEST_ID')
-        d.addErrback(self.checkFailureID, expected='TEST_ID')
-    
-    def checkBlockID(self, result, expected=""):
-        assert(result['blockID'] == expected)
-    
-    
-    def checkFailureID(self, failure, expected=""):
-        assert(failure.blockID == expected)
-    
-    
-    def test_callbacks_added_to_execute(self):
-        """test that
-        update_cell_prompt
-        render_result
-        
-        are added to execute request
-        """
-        
-        d = self.fb.execute("10+10")
-        d.addCallback(self.checkCallbacks)
-    
-    
-    def checkCallbacks(self, result):
-        assert(self.fb.updateCalled)
-        assert(self.fb.renderResultCalled)
-    
-    
-    def test_error_callback_added_to_execute(self):
-        """test that render_error called on execution error"""
-        
-        d = self.fb.execute("raise Exception()")
-        d.addCallback(self.checkRenderError)
-    
-    def checkRenderError(self, result):
-        assert(self.fb.renderErrorCalled)
-    
-    def test_history_returns_expected_block(self):
-        """Make sure history browsing doesn't fail"""
-        
-        blocks = ["a=1","a=2","a=3"]
-        for b in blocks:
-            d = self.fb.execute(b)
-        
-        # d is now the deferred for the last executed block
-        d.addCallback(self.historyTests, blocks)
-        
-    
-    def historyTests(self, result, blocks):
-        """historyTests"""
-        
-        assert(len(blocks) >= 3)
-        assert(self.fb.get_history_previous("") == blocks[-2])
-        assert(self.fb.get_history_previous("") == blocks[-3])
-        assert(self.fb.get_history_next() == blocks[-2])
-    
-    
-    def test_history_returns_none_at_startup(self):
-        """test_history_returns_none_at_startup"""
-        
-        assert(self.fb.get_history_previous("")==None)
-        assert(self.fb.get_history_next()==None)
-    
-    

IPython/frontend/tests/test_process.py

@@ -1,63 +1,67
 # encoding: utf-8
 """
 Test process execution and IO redirection.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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.
 #-------------------------------------------------------------------------------
 
 from cStringIO import StringIO
 from time import sleep
 import sys
 
 from IPython.frontend._process import PipedProcess
+from IPython.testing import decorators as testdec
+
 
 def test_capture_out():
     """ A simple test to see if we can execute a process and get the output.
     """
     s = StringIO()
     p = PipedProcess('echo 1', out_callback=s.write, )
     p.start()
     p.join()
-    assert s.getvalue() == '1\n'
+    result = s.getvalue().rstrip()
+    assert result == '1'
 
 
 def test_io():
     """ Checks that we can send characters on stdin to the process.
     """
     s = StringIO()
     p = PipedProcess(sys.executable + ' -c "a = raw_input(); print a"', 
                             out_callback=s.write, )
     p.start()
     test_string = '12345\n'
     while not hasattr(p, 'process'):
         sleep(0.1)
     p.process.stdin.write(test_string)
     p.join()
-    assert s.getvalue() == test_string
+    result = s.getvalue()
+    assert result == test_string
 
 
 def test_kill():
     """ Check that we can kill a process, and its subprocess.
     """
     s = StringIO()
     p = PipedProcess(sys.executable + ' -c "a = raw_input();"', 
                             out_callback=s.write, )
     p.start()
     while not hasattr(p, 'process'):
         sleep(0.1)
     p.process.kill() 
     assert p.process.poll() is not None
 
 
 if __name__ == '__main__':
     test_capture_out()
     test_io()
     test_kill()
 

IPython/frontend/wx/console_widget.py

@@ -1,428 +1,436
 # encoding: utf-8
 """
 A Wx widget to act as a console and input commands.
 
 This widget deals with prompts and provides an edit buffer
 restricted to after the last prompt.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 wx
 import wx.stc  as  stc
 
 from wx.py import editwindow
+import time
 import sys
 LINESEP = '\n'
 if sys.platform == 'win32':
     LINESEP = '\n\r'
 
 import re
 
 # FIXME: Need to provide an API for non user-generated display on the
 # screen: this should not be editable by the user.
 
 _DEFAULT_SIZE = 10
 if sys.platform == 'darwin':
-    _DEFAULT_STYLE = 12
+    _DEFAULT_SIZE = 12
 
 _DEFAULT_STYLE = {
     'stdout'      : 'fore:#0000FF',
     'stderr'      : 'fore:#007f00',
     'trace'       : 'fore:#FF0000',
 
     'default'     : 'size:%d' % _DEFAULT_SIZE,
     'bracegood'   : 'fore:#00AA00,back:#000000,bold',
     'bracebad'    : 'fore:#FF0000,back:#000000,bold',
 
     # properties for the various Python lexer styles
     'comment'       : 'fore:#007F00',
     'number'        : 'fore:#007F7F',
     'string'        : 'fore:#7F007F,italic',
     'char'          : 'fore:#7F007F,italic',
     'keyword'       : 'fore:#00007F,bold',
     'triple'        : 'fore:#7F0000',
     'tripledouble'  : 'fore:#7F0000',
     'class'         : 'fore:#0000FF,bold,underline',
     'def'           : 'fore:#007F7F,bold',
     'operator'      : 'bold'
     }
 
 # new style numbers
 _STDOUT_STYLE = 15
 _STDERR_STYLE = 16
 _TRACE_STYLE  = 17
 
 
 # system colors
 #SYS_COLOUR_BACKGROUND = wx.SystemSettings.GetColour(wx.SYS_COLOUR_BACKGROUND)
 
 #-------------------------------------------------------------------------------
 # The console widget class
 #-------------------------------------------------------------------------------
 class ConsoleWidget(editwindow.EditWindow):
     """ Specialized styled text control view for console-like workflow.
 
         This widget is mainly interested in dealing with the prompt and
         keeping the cursor inside the editing line.
     """
 
     # This is where the title captured from the ANSI escape sequences are
     # stored.
     title = 'Console'
 
     # The buffer being edited.
     def _set_input_buffer(self, string):
         self.SetSelection(self.current_prompt_pos, self.GetLength())
         self.ReplaceSelection(string)
         self.GotoPos(self.GetLength())
 
     def _get_input_buffer(self):
         """ Returns the text in current edit buffer.
         """
         input_buffer = self.GetTextRange(self.current_prompt_pos,
                                                 self.GetLength())
         input_buffer = input_buffer.replace(LINESEP, '\n')
         return input_buffer
 
     input_buffer = property(_get_input_buffer, _set_input_buffer)
 
     style = _DEFAULT_STYLE.copy()
 
     # Translation table from ANSI escape sequences to color. Override
     # this to specify your colors.
     ANSI_STYLES = {'0;30': [0, 'BLACK'],            '0;31': [1, 'RED'],
                    '0;32': [2, 'GREEN'],            '0;33': [3, 'BROWN'],
                    '0;34': [4, 'BLUE'],             '0;35': [5, 'PURPLE'],
                    '0;36': [6, 'CYAN'],             '0;37': [7, 'LIGHT GREY'],
                    '1;30': [8, 'DARK GREY'],        '1;31': [9, 'RED'],
                    '1;32': [10, 'SEA GREEN'],       '1;33': [11, 'YELLOW'],
                    '1;34': [12, 'LIGHT BLUE'],      '1;35':
                                                      [13, 'MEDIUM VIOLET RED'],
                    '1;36': [14, 'LIGHT STEEL BLUE'], '1;37': [15, 'YELLOW']}
 
     # The color of the carret (call _apply_style() after setting)
     carret_color = 'BLACK'
     
+    # Store the last time a refresh was done
+    _last_refresh_time = 0
+
     #--------------------------------------------------------------------------
     # Public API
     #--------------------------------------------------------------------------
     
     def __init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, 
-                        size=wx.DefaultSize, style=0, ):
+                        size=wx.DefaultSize, style=wx.WANTS_CHARS, ):
         editwindow.EditWindow.__init__(self, parent, id, pos, size, style)
         self._configure_scintilla()
 
         self.Bind(wx.EVT_KEY_DOWN, self._on_key_down)
         self.Bind(wx.EVT_KEY_UP, self._on_key_up)
     
 
     def write(self, text, refresh=True):
         """ Write given text to buffer, while translating the ansi escape
             sequences.
         """
         # XXX: do not put print statements to sys.stdout/sys.stderr in 
         # this method, the print statements will call this method, as 
         # you will end up with an infinit loop
         title = self.title_pat.split(text)
         if len(title)>1:
             self.title = title[-2]
 
         text = self.title_pat.sub('', text)
         segments = self.color_pat.split(text)
         segment = segments.pop(0)
         self.GotoPos(self.GetLength())
         self.StartStyling(self.GetLength(), 0xFF)
         try:
             self.AppendText(segment)
         except UnicodeDecodeError:
             # XXX: Do I really want to skip the exception?
             pass
         
         if segments:
             for ansi_tag, text in zip(segments[::2], segments[1::2]):
                 self.StartStyling(self.GetLength(), 0xFF)
                 try:
                     self.AppendText(text)
                 except UnicodeDecodeError:
                     # XXX: Do I really want to skip the exception?
                     pass
 
                 if ansi_tag not in self.ANSI_STYLES:
                     style = 0
                 else:
                     style = self.ANSI_STYLES[ansi_tag][0]
 
                 self.SetStyling(len(text), style) 
                 
         self.GotoPos(self.GetLength())
         if refresh:
-            # Maybe this is faster than wx.Yield()
-            self.ProcessEvent(wx.PaintEvent())
-            #wx.Yield()
+            current_time = time.time()
+            if current_time - self._last_refresh_time > 0.03:
+                if sys.platform == 'win32':
+                    wx.SafeYield()
+                else:
+                    wx.Yield()
+                #    self.ProcessEvent(wx.PaintEvent())
+                self._last_refresh_time = current_time 
 
    
     def new_prompt(self, prompt):
         """ Prints a prompt at start of line, and move the start of the
             current block there.
 
             The prompt can be given with ascii escape sequences.
         """
         self.write(prompt, refresh=False)
         # now we update our cursor giving end of prompt
         self.current_prompt_pos = self.GetLength()
         self.current_prompt_line = self.GetCurrentLine()
-        wx.Yield()
         self.EnsureCaretVisible()
 
 
     def scroll_to_bottom(self):
         maxrange = self.GetScrollRange(wx.VERTICAL)
         self.ScrollLines(maxrange)
 
 
     def pop_completion(self, possibilities, offset=0):
         """ Pops up an autocompletion menu. Offset is the offset
             in characters of the position at which the menu should
             appear, relativ to the cursor.
         """
         self.AutoCompSetIgnoreCase(False)
         self.AutoCompSetAutoHide(False)
         self.AutoCompSetMaxHeight(len(possibilities))
         self.AutoCompShow(offset, " ".join(possibilities))
 
 
     def get_line_width(self):
         """ Return the width of the line in characters.
         """
         return self.GetSize()[0]/self.GetCharWidth()
 
     #--------------------------------------------------------------------------
     # EditWindow API
     #--------------------------------------------------------------------------
 
     def OnUpdateUI(self, event):
         """ Override the OnUpdateUI of the EditWindow class, to prevent 
             syntax highlighting both for faster redraw, and for more
             consistent look and feel.
         """
 
     #--------------------------------------------------------------------------
     # Private API
     #--------------------------------------------------------------------------
     
     def _apply_style(self):
         """ Applies the colors for the different text elements and the
             carret.
         """
         self.SetCaretForeground(self.carret_color)
 
         #self.StyleClearAll()
         self.StyleSetSpec(stc.STC_STYLE_BRACELIGHT,  
                           "fore:#FF0000,back:#0000FF,bold")
         self.StyleSetSpec(stc.STC_STYLE_BRACEBAD,
                           "fore:#000000,back:#FF0000,bold")
 
         for style in self.ANSI_STYLES.values():
             self.StyleSetSpec(style[0], "bold,fore:%s" % style[1])
 
    
     def _configure_scintilla(self):
         self.SetEOLMode(stc.STC_EOL_LF)
 
         # Ctrl"+" or Ctrl "-" can be used to zoomin/zoomout the text inside 
         # the widget
         self.CmdKeyAssign(ord('+'), stc.STC_SCMOD_CTRL, stc.STC_CMD_ZOOMIN)
         self.CmdKeyAssign(ord('-'), stc.STC_SCMOD_CTRL, stc.STC_CMD_ZOOMOUT)
         # Also allow Ctrl Shift "=" for poor non US keyboard users. 
         self.CmdKeyAssign(ord('='), stc.STC_SCMOD_CTRL|stc.STC_SCMOD_SHIFT, 
                                             stc.STC_CMD_ZOOMIN)
         
         # Keys: we need to clear some of the keys the that don't play
         # well with a console.
         self.CmdKeyClear(ord('D'), stc.STC_SCMOD_CTRL)
         self.CmdKeyClear(ord('L'), stc.STC_SCMOD_CTRL)
         self.CmdKeyClear(ord('T'), stc.STC_SCMOD_CTRL)
         self.CmdKeyClear(ord('A'), stc.STC_SCMOD_CTRL)
 
         self.SetEOLMode(stc.STC_EOL_CRLF)
         self.SetWrapMode(stc.STC_WRAP_CHAR)
         self.SetWrapMode(stc.STC_WRAP_WORD)
         self.SetBufferedDraw(True)
         self.SetUseAntiAliasing(True)
         self.SetLayoutCache(stc.STC_CACHE_PAGE)
         self.SetUndoCollection(False)
         self.SetUseTabs(True)
         self.SetIndent(4)
         self.SetTabWidth(4)
 
         # we don't want scintilla's autocompletion to choose 
         # automaticaly out of a single choice list, as we pop it up
         # automaticaly
         self.AutoCompSetChooseSingle(False)
         self.AutoCompSetMaxHeight(10)
         # XXX: this doesn't seem to have an effect.
         self.AutoCompSetFillUps('\n')
 
         self.SetMargins(3, 3) #text is moved away from border with 3px
         # Suppressing Scintilla margins
         self.SetMarginWidth(0, 0)
         self.SetMarginWidth(1, 0)
         self.SetMarginWidth(2, 0)
 
         self._apply_style()
 
         # Xterm escape sequences
         self.color_pat = re.compile('\x01?\x1b\[(.*?)m\x02?')
         self.title_pat = re.compile('\x1b]0;(.*?)\x07')
 
         #self.SetEdgeMode(stc.STC_EDGE_LINE)
         #self.SetEdgeColumn(80)
 
         # styles
         p = self.style
         self.StyleSetSpec(stc.STC_STYLE_DEFAULT, p['default'])
         self.StyleClearAll()
         self.StyleSetSpec(_STDOUT_STYLE, p['stdout'])
         self.StyleSetSpec(_STDERR_STYLE, p['stderr'])
         self.StyleSetSpec(_TRACE_STYLE, p['trace'])
 
         self.StyleSetSpec(stc.STC_STYLE_BRACELIGHT, p['bracegood'])
         self.StyleSetSpec(stc.STC_STYLE_BRACEBAD, p['bracebad'])
         self.StyleSetSpec(stc.STC_P_COMMENTLINE, p['comment'])
         self.StyleSetSpec(stc.STC_P_NUMBER, p['number'])
         self.StyleSetSpec(stc.STC_P_STRING, p['string'])
         self.StyleSetSpec(stc.STC_P_CHARACTER, p['char'])
         self.StyleSetSpec(stc.STC_P_WORD, p['keyword'])
         self.StyleSetSpec(stc.STC_P_WORD2, p['keyword'])
         self.StyleSetSpec(stc.STC_P_TRIPLE, p['triple'])
         self.StyleSetSpec(stc.STC_P_TRIPLEDOUBLE, p['tripledouble'])
         self.StyleSetSpec(stc.STC_P_CLASSNAME, p['class'])
         self.StyleSetSpec(stc.STC_P_DEFNAME, p['def'])
         self.StyleSetSpec(stc.STC_P_OPERATOR, p['operator'])
         self.StyleSetSpec(stc.STC_P_COMMENTBLOCK, p['comment'])
 
     def _on_key_down(self, event, skip=True):
         """ Key press callback used for correcting behavior for 
             console-like interfaces: the cursor is constraint to be after
             the last prompt.
 
             Return True if event as been catched.
         """
         catched = True
         # Intercept some specific keys.
         if event.KeyCode == ord('L') and event.ControlDown() :
             self.scroll_to_bottom()
         elif event.KeyCode == ord('K') and event.ControlDown() :
             self.input_buffer = ''
         elif event.KeyCode == ord('A') and event.ControlDown() :
             self.GotoPos(self.GetLength())
             self.SetSelectionStart(self.current_prompt_pos)
             self.SetSelectionEnd(self.GetCurrentPos())
             catched = True
         elif event.KeyCode == ord('E') and event.ControlDown() :
             self.GotoPos(self.GetLength())
             catched = True
         elif event.KeyCode == wx.WXK_PAGEUP:
             self.ScrollPages(-1)
         elif event.KeyCode == wx.WXK_PAGEDOWN:
             self.ScrollPages(1)
         elif event.KeyCode == wx.WXK_UP and event.ShiftDown():
             self.ScrollLines(-1)
         elif event.KeyCode == wx.WXK_DOWN and event.ShiftDown():
             self.ScrollLines(1)
         else:
             catched = False
 
         if self.AutoCompActive():
             event.Skip()
         else:
             if event.KeyCode in (13, wx.WXK_NUMPAD_ENTER) and \
                         event.Modifiers in (wx.MOD_NONE, wx.MOD_WIN):
                 catched = True
                 self.CallTipCancel()
                 self.write('\n', refresh=False)
                 # Under windows scintilla seems to be doing funny stuff to the 
                 # line returns here, but the getter for input_buffer filters 
                 # this out.
                 if sys.platform == 'win32':
                     self.input_buffer = self.input_buffer
                 self._on_enter()
 
             elif event.KeyCode == wx.WXK_HOME:
                 if event.Modifiers in (wx.MOD_NONE, wx.MOD_WIN):
                     self.GotoPos(self.current_prompt_pos)
                     catched = True
 
                 elif event.Modifiers == wx.MOD_SHIFT:
                     # FIXME: This behavior is not ideal: if the selection
                     # is already started, it will jump.
                     self.SetSelectionStart(self.current_prompt_pos) 
                     self.SetSelectionEnd(self.GetCurrentPos())
                     catched = True
 
             elif event.KeyCode == wx.WXK_UP:
                 if self.GetCurrentLine() > self.current_prompt_line:
                     if self.GetCurrentLine() == self.current_prompt_line + 1 \
                             and self.GetColumn(self.GetCurrentPos()) < \
                                 self.GetColumn(self.current_prompt_pos):
                         self.GotoPos(self.current_prompt_pos)
                     else:
                         event.Skip()
                 catched = True
 
             elif event.KeyCode in (wx.WXK_LEFT, wx.WXK_BACK):
                 if self.GetCurrentPos() > self.current_prompt_pos:
                     event.Skip()
                 catched = True
 
             if skip and not catched:
                 # Put the cursor back in the edit region
                 if self.GetCurrentPos() < self.current_prompt_pos:
                     self.GotoPos(self.current_prompt_pos)
                 else:
                     event.Skip()
 
         return catched
 
 
     def _on_key_up(self, event, skip=True):
         """ If cursor is outside the editing region, put it back.
         """
         event.Skip()
         if self.GetCurrentPos() < self.current_prompt_pos:
             self.GotoPos(self.current_prompt_pos)
 
 
 
 if __name__ == '__main__':
     # Some simple code to test the console widget.
     class MainWindow(wx.Frame):
         def __init__(self, parent, id, title):
             wx.Frame.__init__(self, parent, id, title, size=(300,250))
             self._sizer = wx.BoxSizer(wx.VERTICAL)
             self.console_widget = ConsoleWidget(self)
             self._sizer.Add(self.console_widget, 1, wx.EXPAND)
             self.SetSizer(self._sizer)
             self.SetAutoLayout(1)
             self.Show(True)
 
     app = wx.PySimpleApp()
     w = MainWindow(None, wx.ID_ANY, 'ConsoleWidget')
     w.SetSize((780, 460))
     w.Show()
 
     app.MainLoop()
 
 

IPython/frontend/wx/wx_frontend.py

@@ -1,510 +1,526
 # encoding: utf-8 -*- test-case-name:
 # FIXME: Need to add tests.
 # ipython1.frontend.wx.tests.test_wx_frontend -*-
 
 """Classes to provide a Wx frontend to the
 IPython.kernel.core.interpreter.
 
 This class inherits from ConsoleWidget, that provides a console-like
 widget to provide a text-rendering widget suitable for a terminal.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #       Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 # Major library imports
 import re
 import __builtin__
 from time import sleep
 import sys
 from threading import Lock
 import string
 
 import wx
 from wx import stc
 
 # Ipython-specific imports.
 from IPython.frontend._process import PipedProcess
 from console_widget import ConsoleWidget
 from IPython.frontend.prefilterfrontend import PrefilterFrontEnd
 
 #-------------------------------------------------------------------------------
 # Constants 
 #-------------------------------------------------------------------------------
 
 _COMPLETE_BUFFER_BG = '#FAFAF1' # Nice green
 _INPUT_BUFFER_BG = '#FDFFD3' # Nice yellow
 _ERROR_BG = '#FFF1F1' # Nice red
 
 _COMPLETE_BUFFER_MARKER = 31
 _ERROR_MARKER = 30
 _INPUT_MARKER = 29
 
 prompt_in1 = \
         '\n\x01\x1b[0;34m\x02In [\x01\x1b[1;34m\x02$number\x01\x1b[0;34m\x02]: \x01\x1b[0m\x02'
 
 prompt_out = \
     '\x01\x1b[0;31m\x02Out[\x01\x1b[1;31m\x02$number\x01\x1b[0;31m\x02]: \x01\x1b[0m\x02'
 
 #-------------------------------------------------------------------------------
 # Classes to implement the Wx frontend
 #-------------------------------------------------------------------------------
 class WxController(ConsoleWidget, PrefilterFrontEnd):
     """Classes to provide a Wx frontend to the
     IPython.kernel.core.interpreter.
 
     This class inherits from ConsoleWidget, that provides a console-like
     widget to provide a text-rendering widget suitable for a terminal.
     """
 
     output_prompt_template = string.Template(prompt_out)
 
     input_prompt_template = string.Template(prompt_in1)
 
     # Print debug info on what is happening to the console.
     debug = False
 
     # The title of the terminal, as captured through the ANSI escape
     # sequences.
     def _set_title(self, title):
             return self.Parent.SetTitle(title)
 
     def _get_title(self):
             return self.Parent.GetTitle()
 
     title = property(_get_title, _set_title)
 
 
     # The buffer being edited.
     # We are duplicating the definition here because of multiple
     # inheritence
     def _set_input_buffer(self, string):
         ConsoleWidget._set_input_buffer(self, string)
         self._colorize_input_buffer()
 
     def _get_input_buffer(self):
         """ Returns the text in current edit buffer.
         """
         return ConsoleWidget._get_input_buffer(self)
 
     input_buffer = property(_get_input_buffer, _set_input_buffer)
 
 
     #--------------------------------------------------------------------------
     # Private Attributes
     #--------------------------------------------------------------------------
 
     # A flag governing the behavior of the input. Can be:
     #
     #       'readline' for readline-like behavior with a prompt 
     #            and an edit buffer.
     #       'raw_input' similar to readline, but triggered by a raw-input
     #           call. Can be used by subclasses to act differently.
     #       'subprocess' for sending the raw input directly to a
     #           subprocess.
     #       'buffering' for buffering of the input, that will be used
     #           when the input state switches back to another state.
     _input_state = 'readline'
 
     # Attribute to store reference to the pipes of a subprocess, if we
     # are running any.
     _running_process = False
 
     # A queue for writing fast streams to the screen without flooding the
     # event loop
     _out_buffer = []
 
     # A lock to lock the _out_buffer to make sure we don't empty it
     # while it is being swapped
     _out_buffer_lock = Lock()
 
+    # The different line markers used to higlight the prompts.
     _markers = dict()
 
     #--------------------------------------------------------------------------
     # Public API
     #--------------------------------------------------------------------------
  
     def __init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition,
-                 size=wx.DefaultSize, style=wx.CLIP_CHILDREN,
+                 size=wx.DefaultSize,
+                 style=wx.CLIP_CHILDREN|wx.WANTS_CHARS,
                  *args, **kwds):
         """ Create Shell instance.
         """
         ConsoleWidget.__init__(self, parent, id, pos, size, style)
         PrefilterFrontEnd.__init__(self, **kwds)
+        
+        # Stick in our own raw_input:
+        self.ipython0.raw_input = self.raw_input
 
         # Marker for complete buffer.
         self.MarkerDefine(_COMPLETE_BUFFER_MARKER, stc.STC_MARK_BACKGROUND,
                                 background=_COMPLETE_BUFFER_BG)
         # Marker for current input buffer.
         self.MarkerDefine(_INPUT_MARKER, stc.STC_MARK_BACKGROUND,
                                 background=_INPUT_BUFFER_BG)
         # Marker for tracebacks.
         self.MarkerDefine(_ERROR_MARKER, stc.STC_MARK_BACKGROUND,
                                 background=_ERROR_BG)
 
         # A time for flushing the write buffer
         BUFFER_FLUSH_TIMER_ID = 100
         self._buffer_flush_timer = wx.Timer(self, BUFFER_FLUSH_TIMER_ID)
         wx.EVT_TIMER(self, BUFFER_FLUSH_TIMER_ID, self._buffer_flush)
 
         if 'debug' in kwds:
             self.debug = kwds['debug']
             kwds.pop('debug')
 
         # Inject self in namespace, for debug
         if self.debug:
             self.shell.user_ns['self'] = self
+        # Inject our own raw_input in namespace
+        self.shell.user_ns['raw_input'] = self.raw_input
 
 
-    def raw_input(self, prompt):
+    def raw_input(self, prompt=''):
         """ A replacement from python's raw_input.
         """
         self.new_prompt(prompt)
         self._input_state = 'raw_input'
         if hasattr(self, '_cursor'):
             del self._cursor 
         self.SetCursor(wx.StockCursor(wx.CURSOR_CROSS))
-        self.waiting = True
         self.__old_on_enter = self._on_enter
+        event_loop = wx.EventLoop()
         def my_on_enter():
-            self.waiting = False
+            event_loop.Exit()
         self._on_enter = my_on_enter
-        # XXX: Busy waiting, ugly.
-        while self.waiting:
-            wx.Yield()
-            sleep(0.1)
+        # XXX: Running a separate event_loop. Ugly.
+        event_loop.Run() 
         self._on_enter = self.__old_on_enter
         self._input_state = 'buffering'
         self._cursor = wx.BusyCursor()
         return self.input_buffer.rstrip('\n')
 
 
     def system_call(self, command_string):
         self._input_state = 'subprocess'
+        event_loop = wx.EventLoop()
+        def _end_system_call():
+            self._input_state = 'buffering'
+            self._running_process = False
+            event_loop.Exit()
+
         self._running_process = PipedProcess(command_string, 
                     out_callback=self.buffered_write,
-                    end_callback = self._end_system_call)
+                    end_callback = _end_system_call)
         self._running_process.start()
-        # XXX: another one of these polling loops to have a blocking
-        # call
-        wx.Yield()
-        while self._running_process:
-            wx.Yield()
-            sleep(0.1)
+        # XXX: Running a separate event_loop. Ugly.
+        event_loop.Run() 
         # Be sure to flush the buffer.
         self._buffer_flush(event=None)
 
 
     def do_calltip(self):
         """ Analyse current and displays useful calltip for it.
         """
         if self.debug:
             print >>sys.__stdout__, "do_calltip" 
         separators =  re.compile('[\s\{\}\[\]\(\)\= ,:]')
         symbol = self.input_buffer
         symbol_string = separators.split(symbol)[-1]
         base_symbol_string = symbol_string.split('.')[0]
         if base_symbol_string in self.shell.user_ns:
             symbol = self.shell.user_ns[base_symbol_string]
         elif base_symbol_string in self.shell.user_global_ns:
             symbol = self.shell.user_global_ns[base_symbol_string]
         elif base_symbol_string in __builtin__.__dict__:
             symbol = __builtin__.__dict__[base_symbol_string]
         else:
             return False
         try:
             for name in symbol_string.split('.')[1:] + ['__doc__']:
                 symbol = getattr(symbol, name)
             self.AutoCompCancel()
-            wx.Yield()
-            self.CallTipShow(self.GetCurrentPos(), symbol)
+            # Check that the symbol can indeed be converted to a string:
+            symbol += ''
+            wx.CallAfter(self.CallTipShow, self.GetCurrentPos(), symbol)
         except:
             # The retrieve symbol couldn't be converted to a string
             pass
 
 
     def _popup_completion(self, create=False):
         """ Updates the popup completion menu if it exists. If create is 
             true, open the menu.
         """
         if self.debug:
-            print >>sys.__stdout__, "_popup_completion", 
+            print >>sys.__stdout__, "_popup_completion" 
         line = self.input_buffer
-        if (self.AutoCompActive() and not line[-1] == '.') \
+        if (self.AutoCompActive() and line and not line[-1] == '.') \
                     or create==True:
             suggestion, completions = self.complete(line)
             offset=0
             if completions:
                 complete_sep =  re.compile('[\s\{\}\[\]\(\)\= ,:]')
                 residual = complete_sep.split(line)[-1]
                 offset = len(residual)
                 self.pop_completion(completions, offset=offset)
                 if self.debug:
                     print >>sys.__stdout__, completions 
 
 
     def buffered_write(self, text):
         """ A write method for streams, that caches the stream in order
             to avoid flooding the event loop.
 
             This can be called outside of the main loop, in separate
             threads.
         """
         self._out_buffer_lock.acquire()
         self._out_buffer.append(text)
         self._out_buffer_lock.release()
         if not self._buffer_flush_timer.IsRunning():
             wx.CallAfter(self._buffer_flush_timer.Start, 
                                         milliseconds=100, oneShot=True)
 
 
     #--------------------------------------------------------------------------
     # LineFrontEnd interface 
     #--------------------------------------------------------------------------
  
     def execute(self, python_string, raw_string=None):
         self._input_state = 'buffering'
         self.CallTipCancel()
         self._cursor = wx.BusyCursor()
         if raw_string is None:
             raw_string = python_string
         end_line = self.current_prompt_line \
                         + max(1,  len(raw_string.split('\n'))-1)
         for i in range(self.current_prompt_line, end_line):
             if i in self._markers:
                 self.MarkerDeleteHandle(self._markers[i])
             self._markers[i] = self.MarkerAdd(i, _COMPLETE_BUFFER_MARKER)
-        # Update the display:
-        wx.Yield()
-        self.GotoPos(self.GetLength())
-        PrefilterFrontEnd.execute(self, python_string, raw_string=raw_string)
+        # Use a callafter to update the display robustly under windows
+        def callback():
+            self.GotoPos(self.GetLength())
+            PrefilterFrontEnd.execute(self, python_string, 
+                                            raw_string=raw_string)
+        wx.CallAfter(callback)
 
     def save_output_hooks(self):    
         self.__old_raw_input = __builtin__.raw_input
         PrefilterFrontEnd.save_output_hooks(self)
 
     def capture_output(self):
-        __builtin__.raw_input = self.raw_input
         self.SetLexer(stc.STC_LEX_NULL)
         PrefilterFrontEnd.capture_output(self)
+        __builtin__.raw_input = self.raw_input
         
     
     def release_output(self):
         __builtin__.raw_input = self.__old_raw_input
         PrefilterFrontEnd.release_output(self)
         self.SetLexer(stc.STC_LEX_PYTHON)
 
 
     def after_execute(self):
         PrefilterFrontEnd.after_execute(self)
         # Clear the wait cursor
         if hasattr(self, '_cursor'):
             del self._cursor
         self.SetCursor(wx.StockCursor(wx.CURSOR_CHAR))
 
 
     def show_traceback(self):
         start_line = self.GetCurrentLine()
         PrefilterFrontEnd.show_traceback(self)
-        wx.Yield()
+        self.ProcessEvent(wx.PaintEvent())
+        #wx.Yield()
         for i in range(start_line, self.GetCurrentLine()):
             self._markers[i] = self.MarkerAdd(i, _ERROR_MARKER)
 
     
     #--------------------------------------------------------------------------
+    # FrontEndBase interface 
+    #--------------------------------------------------------------------------
+    
+    def render_error(self, e):
+        start_line = self.GetCurrentLine()
+        self.write('\n' + e + '\n')
+        for i in range(start_line, self.GetCurrentLine()):
+            self._markers[i] = self.MarkerAdd(i, _ERROR_MARKER)
+
+
+    #--------------------------------------------------------------------------
     # ConsoleWidget interface 
     #--------------------------------------------------------------------------
 
     def new_prompt(self, prompt):
         """ Display a new prompt, and start a new input buffer.
         """
         self._input_state = 'readline'
         ConsoleWidget.new_prompt(self, prompt)
         i = self.current_prompt_line
         self._markers[i] = self.MarkerAdd(i, _INPUT_MARKER)
 
 
     def write(self, *args, **kwargs):
         # Avoid multiple inheritence, be explicit about which
         # parent method class gets called
         ConsoleWidget.write(self, *args, **kwargs)
 
 
     def _on_key_down(self, event, skip=True):
         """ Capture the character events, let the parent
             widget handle them, and put our logic afterward.
         """
         # FIXME: This method needs to be broken down in smaller ones.
         current_line_number = self.GetCurrentLine()
         if event.KeyCode in (ord('c'), ord('C')) and event.ControlDown():
             # Capture Control-C
             if self._input_state == 'subprocess':
                 if self.debug:
                     print >>sys.__stderr__, 'Killing running process'
-                self._running_process.process.kill()
+                if hasattr(self._running_process, 'process'):
+                    self._running_process.process.kill()
             elif self._input_state == 'buffering':
                 if self.debug:
                     print >>sys.__stderr__, 'Raising KeyboardInterrupt'
                 raise KeyboardInterrupt
                 # XXX: We need to make really sure we
                 # get back to a prompt.
         elif self._input_state == 'subprocess' and (
                 ( event.KeyCode<256 and
                         not event.ControlDown() )
                     or 
                 ( event.KeyCode in (ord('d'), ord('D')) and
                   event.ControlDown())):
             #  We are running a process, we redirect keys.
             ConsoleWidget._on_key_down(self, event, skip=skip)
             char = chr(event.KeyCode)
             # Deal with some inconsistency in wx keycodes:
             if char == '\r':
                 char = '\n'
             elif not event.ShiftDown():
                 char = char.lower()
             if event.ControlDown() and event.KeyCode in (ord('d'), ord('D')):
                 char = '\04'
             self._running_process.process.stdin.write(char)
             self._running_process.process.stdin.flush()
-        elif event.KeyCode in (ord('('), 57):
+        elif event.KeyCode in (ord('('), 57, 53):
             # Calltips
             event.Skip()
             self.do_calltip()
         elif self.AutoCompActive() and not event.KeyCode == ord('\t'):
             event.Skip()
             if event.KeyCode in (wx.WXK_BACK, wx.WXK_DELETE): 
                 wx.CallAfter(self._popup_completion, create=True)
             elif not event.KeyCode in (wx.WXK_UP, wx.WXK_DOWN, wx.WXK_LEFT,
                             wx.WXK_RIGHT, wx.WXK_ESCAPE):
                 wx.CallAfter(self._popup_completion)
         else:
             # Up history
             if event.KeyCode == wx.WXK_UP and (
                     ( current_line_number == self.current_prompt_line and
                         event.Modifiers in (wx.MOD_NONE, wx.MOD_WIN) ) 
                     or event.ControlDown() ):
                 new_buffer = self.get_history_previous(
                                             self.input_buffer)
                 if new_buffer is not None:
                     self.input_buffer = new_buffer
                     if self.GetCurrentLine() > self.current_prompt_line:
                         # Go to first line, for seemless history up.
                         self.GotoPos(self.current_prompt_pos)
             # Down history
             elif event.KeyCode == wx.WXK_DOWN and (
                     ( current_line_number == self.LineCount -1 and
                         event.Modifiers in (wx.MOD_NONE, wx.MOD_WIN) ) 
                     or event.ControlDown() ):
                 new_buffer = self.get_history_next()
                 if new_buffer is not None:
                     self.input_buffer = new_buffer
             # Tab-completion
             elif event.KeyCode == ord('\t'):
-                last_line = self.input_buffer.split('\n')[-1]
-                if not re.match(r'^\s*$', last_line):
+                current_line, current_line_number = self.CurLine
+                if not re.match(r'^\s*$', current_line):
                     self.complete_current_input()
                     if self.AutoCompActive():
                         wx.CallAfter(self._popup_completion, create=True)
                 else:
                     event.Skip()
             else:
                 ConsoleWidget._on_key_down(self, event, skip=skip)
 
 
     def _on_key_up(self, event, skip=True):
         """ Called when any key is released.
         """
         if event.KeyCode in (59, ord('.')):
             # Intercepting '.'
             event.Skip()
-            self._popup_completion(create=True)
+            wx.CallAfter(self._popup_completion, create=True)
         else:
             ConsoleWidget._on_key_up(self, event, skip=skip)
 
 
     def _on_enter(self):
         """ Called on return key down, in readline input_state.
         """
         if self.debug:
             print >>sys.__stdout__, repr(self.input_buffer)
         PrefilterFrontEnd._on_enter(self)
 
 
     #--------------------------------------------------------------------------
     # EditWindow API
     #--------------------------------------------------------------------------
 
     def OnUpdateUI(self, event):
         """ Override the OnUpdateUI of the EditWindow class, to prevent 
             syntax highlighting both for faster redraw, and for more
             consistent look and feel.
         """
         if not self._input_state == 'readline':
             ConsoleWidget.OnUpdateUI(self, event)
 
     #--------------------------------------------------------------------------
     # Private API
     #--------------------------------------------------------------------------
  
-    def _end_system_call(self):
-        """ Called at the end of a system call.
-        """
-        self._input_state = 'buffering'
-        self._running_process = False
-
-
     def _buffer_flush(self, event):
         """ Called by the timer to flush the write buffer.
             
             This is always called in the mainloop, by the wx timer.
         """
         self._out_buffer_lock.acquire()
         _out_buffer = self._out_buffer
         self._out_buffer = []
         self._out_buffer_lock.release()
         self.write(''.join(_out_buffer), refresh=False)
 
 
     def _colorize_input_buffer(self):
         """ Keep the input buffer lines at a bright color.
         """
         if not self._input_state in ('readline', 'raw_input'):
             return
         end_line = self.GetCurrentLine()
         if not sys.platform == 'win32':
             end_line += 1
         for i in range(self.current_prompt_line, end_line):
             if i in self._markers:
                 self.MarkerDeleteHandle(self._markers[i])
             self._markers[i] = self.MarkerAdd(i, _INPUT_MARKER)
 
 
 if __name__ == '__main__':
     class MainWindow(wx.Frame):
         def __init__(self, parent, id, title):
             wx.Frame.__init__(self, parent, id, title, size=(300,250))
             self._sizer = wx.BoxSizer(wx.VERTICAL)
             self.shell = WxController(self)
             self._sizer.Add(self.shell, 1, wx.EXPAND)
             self.SetSizer(self._sizer)
             self.SetAutoLayout(1)
             self.Show(True)
 
     app = wx.PySimpleApp()
     frame = MainWindow(None, wx.ID_ANY, 'Ipython')
     frame.shell.SetFocus()
     frame.SetSize((680, 460))
     self = frame.shell
 
     app.MainLoop()
 

IPython/frontend/zopeinterface.py

@@ -1,34 +1,27
 # encoding: utf-8
 # -*- test-case-name: IPython.frontend.tests.test_frontendbase -*-
 """
 zope.interface mock. If zope is installed, this module provides a zope
 interface classes, if not it provides mocks for them.
 
 Classes provided: 
 Interface, Attribute, implements, classProvides
 """
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 string
-import uuid
-import _ast
-
 try:
     from zope.interface import Interface, Attribute, implements, classProvides
 except ImportError:
     #zope.interface is not available
     Interface = object
     def Attribute(name, doc): pass
     def implements(interface): pass
     def classProvides(interface): pass
 

IPython/genutils.py

@@ -1,2132 +1,2164
 # -*- coding: utf-8 -*-
 """
 General purpose utilities.
 
 This is a grab-bag of stuff I find useful in most programs I write. Some of
 these things are also convenient when working at the command line.
 
 $Id: genutils.py 2998 2008-01-31 10:06:04Z vivainio $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001-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 IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 #****************************************************************************
 # required modules from the Python standard library
 import __main__
 import commands
 try:
     import doctest
 except ImportError:
     pass
 import os
 import platform
 import re
 import shlex
 import shutil
 import subprocess
 import sys
 import tempfile
 import time
 import types
 import warnings
 
 # Curses and termios are Unix-only modules
 try:
     import curses
     # We need termios as well, so if its import happens to raise, we bail on
     # using curses altogether.
     import termios
 except ImportError:
     USE_CURSES = False
 else:
     # Curses on Solaris may not be complete, so we can't use it there
     USE_CURSES = hasattr(curses,'initscr')
 
 # Other IPython utilities
 import IPython
 from IPython.Itpl import Itpl,itpl,printpl
 from IPython import DPyGetOpt, platutils
 from IPython.generics import result_display
 import IPython.ipapi
 from IPython.external.path import path
 if os.name == "nt":
     from IPython.winconsole import get_console_size
 
 try:
     set
 except:
     from sets import Set as set
 
 
 #****************************************************************************
 # Exceptions
 class Error(Exception):
     """Base class for exceptions in this module."""
     pass
 
 #----------------------------------------------------------------------------
 class IOStream:
     def __init__(self,stream,fallback):
         if not hasattr(stream,'write') or not hasattr(stream,'flush'):
             stream = fallback
         self.stream = stream
         self._swrite = stream.write
         self.flush = stream.flush
 
     def write(self,data):
         try:
             self._swrite(data)
         except:
             try:
                 # print handles some unicode issues which may trip a plain
                 # write() call.  Attempt to emulate write() by using a
                 # trailing comma
                 print >> self.stream, data,
             except:
                 # if we get here, something is seriously broken.
                 print >> sys.stderr, \
                       'ERROR - failed to write data to stream:', self.stream
 
     def close(self):
         pass
 
 
 class IOTerm:
     """ Term holds the file or file-like objects for handling I/O operations.
 
     These are normally just sys.stdin, sys.stdout and sys.stderr but for
     Windows they can can replaced to allow editing the strings before they are
     displayed."""
 
     # In the future, having IPython channel all its I/O operations through
     # this class will make it easier to embed it into other environments which
     # are not a normal terminal (such as a GUI-based shell)
     def __init__(self,cin=None,cout=None,cerr=None):
         self.cin  = IOStream(cin,sys.stdin)
         self.cout = IOStream(cout,sys.stdout)
         self.cerr = IOStream(cerr,sys.stderr)
 
 # Global variable to be used for all I/O
 Term = IOTerm()
 
 import IPython.rlineimpl as readline
 # Remake Term to use the readline i/o facilities
 if sys.platform == 'win32' and readline.have_readline:
 
     Term = IOTerm(cout=readline._outputfile,cerr=readline._outputfile)
 
 
 #****************************************************************************
 # Generic warning/error printer, used by everything else
 def warn(msg,level=2,exit_val=1):
     """Standard warning printer. Gives formatting consistency.
 
     Output is sent to Term.cerr (sys.stderr by default).
 
     Options:
 
     -level(2): allows finer control:
       0 -> Do nothing, dummy function.
       1 -> Print message.
       2 -> Print 'WARNING:' + message. (Default level).
       3 -> Print 'ERROR:' + message.
       4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
 
     -exit_val (1): exit value returned by sys.exit() for a level 4
     warning. Ignored for all other levels."""
 
     if level>0:
         header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
         print >> Term.cerr, '%s%s' % (header[level],msg)
         if level == 4:
             print >> Term.cerr,'Exiting.\n'
             sys.exit(exit_val)
 
 def info(msg):
     """Equivalent to warn(msg,level=1)."""
 
     warn(msg,level=1)
 
 def error(msg):
     """Equivalent to warn(msg,level=3)."""
 
     warn(msg,level=3)
 
 def fatal(msg,exit_val=1):
     """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
 
     warn(msg,exit_val=exit_val,level=4)
 
 #---------------------------------------------------------------------------
 # Debugging routines
 #
 def debugx(expr,pre_msg=''):
     """Print the value of an expression from the caller's frame.
 
     Takes an expression, evaluates it in the caller's frame and prints both
     the given expression and the resulting value (as well as a debug mark
     indicating the name of the calling function.  The input must be of a form
     suitable for eval().
 
     An optional message can be passed, which will be prepended to the printed
     expr->value pair."""
 
     cf = sys._getframe(1)
     print '[DBG:%s] %s%s -> %r' % (cf.f_code.co_name,pre_msg,expr,
                                    eval(expr,cf.f_globals,cf.f_locals))
 
 # deactivate it by uncommenting the following line, which makes it a no-op
 #def debugx(expr,pre_msg=''): pass
 
 #----------------------------------------------------------------------------
 StringTypes = types.StringTypes
 
 # Basic timing functionality
 
 # If possible (Unix), use the resource module instead of time.clock()
 try:
     import resource
     def clocku():
         """clocku() -> floating point number
 
         Return the *USER* CPU time in seconds since the start of the process.
         This is done via a call to resource.getrusage, so it avoids the
         wraparound problems in time.clock()."""
 
         return resource.getrusage(resource.RUSAGE_SELF)[0]
 
     def clocks():
         """clocks() -> floating point number
 
         Return the *SYSTEM* CPU time in seconds since the start of the process.
         This is done via a call to resource.getrusage, so it avoids the
         wraparound problems in time.clock()."""
 
         return resource.getrusage(resource.RUSAGE_SELF)[1]
 
     def clock():
         """clock() -> floating point number
 
         Return the *TOTAL USER+SYSTEM* CPU time in seconds since the start of
         the process.  This is done via a call to resource.getrusage, so it
         avoids the wraparound problems in time.clock()."""
 
         u,s = resource.getrusage(resource.RUSAGE_SELF)[:2]
         return u+s
 
     def clock2():
         """clock2() -> (t_user,t_system)
 
         Similar to clock(), but return a tuple of user/system times."""
         return resource.getrusage(resource.RUSAGE_SELF)[:2]
 
 except ImportError:
     # There is no distinction of user/system time under windows, so we just use
     # time.clock() for everything...
     clocku = clocks = clock = time.clock
     def clock2():
         """Under windows, system CPU time can't be measured.
 
         This just returns clock() and zero."""
         return time.clock(),0.0
 
 def timings_out(reps,func,*args,**kw):
     """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
 
     Execute a function reps times, return a tuple with the elapsed total
     CPU time in seconds, the time per call and the function's output.
 
     Under Unix, the return value is the sum of user+system time consumed by
     the process, computed via the resource module.  This prevents problems
     related to the wraparound effect which the time.clock() function has.
 
     Under Windows the return value is in wall clock seconds. See the
     documentation for the time module for more details."""
 
     reps = int(reps)
     assert reps >=1, 'reps must be >= 1'
     if reps==1:
         start = clock()
         out = func(*args,**kw)
         tot_time = clock()-start
     else:
         rng = xrange(reps-1) # the last time is executed separately to store output
         start = clock()
         for dummy in rng: func(*args,**kw)
         out = func(*args,**kw)  # one last time
         tot_time = clock()-start
     av_time = tot_time / reps
     return tot_time,av_time,out
 
 def timings(reps,func,*args,**kw):
     """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
 
     Execute a function reps times, return a tuple with the elapsed total CPU
     time in seconds and the time per call. These are just the first two values
     in timings_out()."""
 
     return timings_out(reps,func,*args,**kw)[0:2]
 
 def timing(func,*args,**kw):
     """timing(func,*args,**kw) -> t_total
 
     Execute a function once, return the elapsed total CPU time in
     seconds. This is just the first value in timings_out()."""
 
     return timings_out(1,func,*args,**kw)[0]
 
 #****************************************************************************
 # file and system
 
 def arg_split(s,posix=False):
     """Split a command line's arguments in a shell-like manner.
 
     This is a modified version of the standard library's shlex.split()
     function, but with a default of posix=False for splitting, so that quotes
     in inputs are respected."""
 
     # XXX - there may be unicode-related problems here!!!  I'm not sure that
     # shlex is truly unicode-safe, so it might be necessary to do
     #
     # s = s.encode(sys.stdin.encoding)
     #
     # first, to ensure that shlex gets a normal string.  Input from anyone who
     # knows more about unicode and shlex than I would be good to have here...
     lex = shlex.shlex(s, posix=posix)
     lex.whitespace_split = True
     return list(lex)
 
 def system(cmd,verbose=0,debug=0,header=''):
     """Execute a system command, return its exit status.
 
     Options:
 
     - verbose (0): print the command to be executed.
 
     - debug (0): only print, do not actually execute.
 
     - header (''): Header to print on screen prior to the executed command (it
     is only prepended to the command, no newlines are added).
 
     Note: a stateful version of this function is available through the
     SystemExec class."""
 
     stat = 0
     if verbose or debug: print header+cmd
     sys.stdout.flush()
     if not debug: stat = os.system(cmd)
     return stat
 
 def abbrev_cwd():
     """ Return abbreviated version of cwd, e.g. d:mydir """
     cwd = os.getcwd().replace('\\','/')
     drivepart = ''
     tail = cwd
     if sys.platform == 'win32':
         if len(cwd) < 4:
             return cwd
         drivepart,tail = os.path.splitdrive(cwd)
 
 
     parts = tail.split('/')
     if len(parts) > 2:
         tail = '/'.join(parts[-2:])
 
     return (drivepart + (
         cwd == '/' and '/' or tail))
 
 
 # This function is used by ipython in a lot of places to make system calls.
 # We need it to be slightly different under win32, due to the vagaries of
 # 'network shares'.  A win32 override is below.
 
 def shell(cmd,verbose=0,debug=0,header=''):
     """Execute a command in the system shell, always return None.
 
     Options:
 
     - verbose (0): print the command to be executed.
 
     - debug (0): only print, do not actually execute.
 
     - header (''): Header to print on screen prior to the executed command (it
     is only prepended to the command, no newlines are added).
 
     Note: this is similar to genutils.system(), but it returns None so it can
     be conveniently used in interactive loops without getting the return value
     (typically 0) printed many times."""
 
     stat = 0
     if verbose or debug: print header+cmd
     # flush stdout so we don't mangle python's buffering
     sys.stdout.flush()
 
     if not debug:
         platutils.set_term_title("IPy " + cmd)
         os.system(cmd)
         platutils.set_term_title("IPy " + abbrev_cwd())
 
 # override shell() for win32 to deal with network shares
 if os.name in ('nt','dos'):
 
     shell_ori = shell
 
     def shell(cmd,verbose=0,debug=0,header=''):
         if os.getcwd().startswith(r"\\"):
             path = os.getcwd()
             # change to c drive (cannot be on UNC-share when issuing os.system,
             # as cmd.exe cannot handle UNC addresses)
             os.chdir("c:")
             # issue pushd to the UNC-share and then run the command
             try:
                 shell_ori('"pushd %s&&"'%path+cmd,verbose,debug,header)
             finally:
                 os.chdir(path)
         else:
             shell_ori(cmd,verbose,debug,header)
 
     shell.__doc__ = shell_ori.__doc__
 
 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
     """Dummy substitute for perl's backquotes.
 
     Executes a command and returns the output.
 
     Accepts the same arguments as system(), plus:
 
     - split(0): if true, the output is returned as a list split on newlines.
 
     Note: a stateful version of this function is available through the
     SystemExec class.
 
     This is pretty much deprecated and rarely used,
     genutils.getoutputerror may be what you need.
 
     """
 
     if verbose or debug: print header+cmd
     if not debug:
         output = os.popen(cmd).read()
         # stipping last \n is here for backwards compat.
         if output.endswith('\n'):
             output = output[:-1]
         if split:
             return output.split('\n')
         else:
             return output
 
 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
     """Return (standard output,standard error) of executing cmd in a shell.
 
     Accepts the same arguments as system(), plus:
 
     - split(0): if true, each of stdout/err is returned as a list split on
     newlines.
 
     Note: a stateful version of this function is available through the
     SystemExec class."""
 
     if verbose or debug: print header+cmd
     if not cmd:
         if split:
             return [],[]
         else:
             return '',''
     if not debug:
         pin,pout,perr = os.popen3(cmd)
         tout = pout.read().rstrip()
         terr = perr.read().rstrip()
         pin.close()
         pout.close()
         perr.close()
         if split:
             return tout.split('\n'),terr.split('\n')
         else:
             return tout,terr
 
 # for compatibility with older naming conventions
 xsys = system
 bq = getoutput
 
 class SystemExec:
     """Access the system and getoutput functions through a stateful interface.
 
     Note: here we refer to the system and getoutput functions from this
     library, not the ones from the standard python library.
 
     This class offers the system and getoutput functions as methods, but the
     verbose, debug and header parameters can be set for the instance (at
     creation time or later) so that they don't need to be specified on each
     call.
 
     For efficiency reasons, there's no way to override the parameters on a
     per-call basis other than by setting instance attributes. If you need
     local overrides, it's best to directly call system() or getoutput().
 
     The following names are provided as alternate options:
      - xsys: alias to system
      - bq: alias to getoutput
 
     An instance can then be created as:
     >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
     """
 
     def __init__(self,verbose=0,debug=0,header='',split=0):
         """Specify the instance's values for verbose, debug and header."""
         setattr_list(self,'verbose debug header split')
 
     def system(self,cmd):
         """Stateful interface to system(), with the same keyword parameters."""
 
         system(cmd,self.verbose,self.debug,self.header)
 
     def shell(self,cmd):
         """Stateful interface to shell(), with the same keyword parameters."""
 
         shell(cmd,self.verbose,self.debug,self.header)
 
     xsys = system  # alias
 
     def getoutput(self,cmd):
         """Stateful interface to getoutput()."""
 
         return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
 
     def getoutputerror(self,cmd):
         """Stateful interface to getoutputerror()."""
 
         return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
 
     bq = getoutput  # alias
 
 #-----------------------------------------------------------------------------
 def mutex_opts(dict,ex_op):
     """Check for presence of mutually exclusive keys in a dict.
 
     Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
     for op1,op2 in ex_op:
         if op1 in dict and op2 in dict:
             raise ValueError,'\n*** ERROR in Arguments *** '\
                   'Options '+op1+' and '+op2+' are mutually exclusive.'
 
 #-----------------------------------------------------------------------------
 def get_py_filename(name):
     """Return a valid python filename in the current directory.
 
     If the given name is not a file, it adds '.py' and searches again.
     Raises IOError with an informative message if the file isn't found."""
 
     name = os.path.expanduser(name)
     if not os.path.isfile(name) and not name.endswith('.py'):
         name += '.py'
     if os.path.isfile(name):
         return name
     else:
         raise IOError,'File `%s` not found.' % name
 
 #-----------------------------------------------------------------------------
 def filefind(fname,alt_dirs = None):
     """Return the given filename either in the current directory, if it
     exists, or in a specified list of directories.
 
     ~ expansion is done on all file and directory names.
 
     Upon an unsuccessful search, raise an IOError exception."""
 
     if alt_dirs is None:
         try:
             alt_dirs = get_home_dir()
         except HomeDirError:
             alt_dirs = os.getcwd()
     search = [fname] + list_strings(alt_dirs)
     search = map(os.path.expanduser,search)
     #print 'search list for',fname,'list:',search  # dbg
     fname = search[0]
     if os.path.isfile(fname):
         return fname
     for direc in search[1:]:
         testname = os.path.join(direc,fname)
         #print 'testname',testname  # dbg
         if os.path.isfile(testname):
             return testname
     raise IOError,'File' + `fname` + \
           ' not found in current or supplied directories:' + `alt_dirs`
 
 #----------------------------------------------------------------------------
 def file_read(filename):
     """Read a file and close it.  Returns the file source."""
     fobj = open(filename,'r');
     source = fobj.read();
     fobj.close()
     return source
 
 def file_readlines(filename):
     """Read a file and close it.  Returns the file source using readlines()."""
     fobj = open(filename,'r');
     lines = fobj.readlines();
     fobj.close()
     return lines
 
 #----------------------------------------------------------------------------
 def target_outdated(target,deps):
     """Determine whether a target is out of date.
 
     target_outdated(target,deps) -> 1/0
 
     deps: list of filenames which MUST exist.
     target: single filename which may or may not exist.
 
     If target doesn't exist or is older than any file listed in deps, return
     true, otherwise return false.
     """
     try:
         target_time = os.path.getmtime(target)
     except os.error:
         return 1
     for dep in deps:
         dep_time = os.path.getmtime(dep)
         if dep_time > target_time:
             #print "For target",target,"Dep failed:",dep # dbg
             #print "times (dep,tar):",dep_time,target_time # dbg
             return 1
     return 0
 
 #-----------------------------------------------------------------------------
 def target_update(target,deps,cmd):
     """Update a target with a given command given a list of dependencies.
 
     target_update(target,deps,cmd) -> runs cmd if target is outdated.
 
     This is just a wrapper around target_outdated() which calls the given
     command if target is outdated."""
 
     if target_outdated(target,deps):
         xsys(cmd)
 
 #----------------------------------------------------------------------------
 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
 
 #----------------------------------------------------------------------------
 def process_cmdline(argv,names=[],defaults={},usage=''):
     """ Process command-line options and arguments.
 
     Arguments:
 
     - argv: list of arguments, typically sys.argv.
 
     - names: list of option names. See DPyGetOpt docs for details on options
     syntax.
 
     - defaults: dict of default values.
 
     - usage: optional usage notice to print if a wrong argument is passed.
 
     Return a dict of options and a list of free arguments."""
 
     getopt = DPyGetOpt.DPyGetOpt()
     getopt.setIgnoreCase(0)
     getopt.parseConfiguration(names)
 
     try:
         getopt.processArguments(argv)
     except DPyGetOpt.ArgumentError, exc:
         print usage
         warn('"%s"' % exc,level=4)
 
     defaults.update(getopt.optionValues)
     args = getopt.freeValues
 
     return defaults,args
 
 #----------------------------------------------------------------------------
 def optstr2types(ostr):
     """Convert a string of option names to a dict of type mappings.
 
     optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
 
     This is used to get the types of all the options in a string formatted
     with the conventions of DPyGetOpt. The 'type' None is used for options
     which are strings (they need no further conversion). This function's main
     use is to get a typemap for use with read_dict().
     """
 
     typeconv = {None:'',int:'',float:''}
     typemap = {'s':None,'i':int,'f':float}
     opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
 
     for w in ostr.split():
         oname,alias,otype = opt_re.match(w).groups()
         if otype == '' or alias == '!':   # simple switches are integers too
             otype = 'i'
         typeconv[typemap[otype]] += oname + ' '
     return typeconv
 
 #----------------------------------------------------------------------------
 def read_dict(filename,type_conv=None,**opt):
     r"""Read a dictionary of key=value pairs from an input file, optionally
     performing conversions on the resulting values.
 
     read_dict(filename,type_conv,**opt) -> dict
 
     Only one value per line is accepted, the format should be
      # optional comments are ignored
      key value\n
 
     Args:
 
       - type_conv: A dictionary specifying which keys need to be converted to
       which types. By default all keys are read as strings. This dictionary
       should have as its keys valid conversion functions for strings
       (int,long,float,complex, or your own).  The value for each key
       (converter) should be a whitespace separated string containing the names
       of all the entries in the file to be converted using that function. For
       keys to be left alone, use None as the conversion function (only needed
       with purge=1, see below).
 
       - opt: dictionary with extra options as below (default in parens)
 
         purge(0): if set to 1, all keys *not* listed in type_conv are purged out
         of the dictionary to be returned. If purge is going to be used, the
         set of keys to be left as strings also has to be explicitly specified
         using the (non-existent) conversion function None.
 
         fs(None): field separator. This is the key/value separator to be used
         when parsing the file. The None default means any whitespace [behavior
         of string.split()].
 
         strip(0): if 1, strip string values of leading/trailinig whitespace.
 
         warn(1): warning level if requested keys are not found in file.
           - 0: silently ignore.
           - 1: inform but proceed.
           - 2: raise KeyError exception.
 
         no_empty(0): if 1, remove keys with whitespace strings as a value.
 
         unique([]): list of keys (or space separated string) which can't be
         repeated. If one such key is found in the file, each new instance
         overwrites the previous one. For keys not listed here, the behavior is
         to make a list of all appearances.
 
     Example:
 
     If the input file test.ini contains (we put it in a string to keep the test
     self-contained):
 
     >>> test_ini = '''\
     ... i 3
     ... x 4.5
     ... y 5.5
     ... s hi ho'''
 
     Then we can use it as follows:
     >>> type_conv={int:'i',float:'x',None:'s'}
 
     >>> d = read_dict(test_ini)
 
     >>> sorted(d.items())
     [('i', '3'), ('s', 'hi ho'), ('x', '4.5'), ('y', '5.5')]
 
     >>> d = read_dict(test_ini,type_conv)
 
     >>> sorted(d.items())
     [('i', 3), ('s', 'hi ho'), ('x', 4.5), ('y', '5.5')]
 
     >>> d = read_dict(test_ini,type_conv,purge=True)
 
     >>> sorted(d.items())
     [('i', 3), ('s', 'hi ho'), ('x', 4.5)]
     """
 
     # starting config
     opt.setdefault('purge',0)
     opt.setdefault('fs',None)  # field sep defaults to any whitespace
     opt.setdefault('strip',0)
     opt.setdefault('warn',1)
     opt.setdefault('no_empty',0)
     opt.setdefault('unique','')
     if type(opt['unique']) in StringTypes:
         unique_keys = qw(opt['unique'])
     elif type(opt['unique']) in (types.TupleType,types.ListType):
         unique_keys = opt['unique']
     else:
         raise ValueError, 'Unique keys must be given as a string, List or Tuple'
 
     dict = {}
 
     # first read in table of values as strings
     if '\n' in filename:
         lines = filename.splitlines()
         file = None
     else:
         file = open(filename,'r')
         lines = file.readlines()
     for line in lines:
         line = line.strip()
         if len(line) and line[0]=='#': continue
         if len(line)>0:
             lsplit = line.split(opt['fs'],1)
             try:
                 key,val = lsplit
             except ValueError:
                 key,val = lsplit[0],''
             key = key.strip()
             if opt['strip']: val = val.strip()
             if val == "''" or val == '""': val = ''
             if opt['no_empty'] and (val=='' or val.isspace()):
                 continue
             # if a key is found more than once in the file, build a list
             # unless it's in the 'unique' list. In that case, last found in file
             # takes precedence. User beware.
             try:
                 if dict[key] and key in unique_keys:
                     dict[key] = val
                 elif type(dict[key]) is types.ListType:
                     dict[key].append(val)
                 else:
                     dict[key] = [dict[key],val]
             except KeyError:
                 dict[key] = val
     # purge if requested
     if opt['purge']:
         accepted_keys = qwflat(type_conv.values())
         for key in dict.keys():
             if key in accepted_keys: continue
             del(dict[key])
     # now convert if requested
     if type_conv==None: return dict
     conversions = type_conv.keys()
     try: conversions.remove(None)
     except: pass
     for convert in conversions:
         for val in qw(type_conv[convert]):
             try:
                 dict[val] = convert(dict[val])
             except KeyError,e:
                 if opt['warn'] == 0:
                     pass
                 elif opt['warn'] == 1:
                     print >>sys.stderr, 'Warning: key',val,\
                           'not found in file',filename
                 elif opt['warn'] == 2:
                     raise KeyError,e
                 else:
                     raise ValueError,'Warning level must be 0,1 or 2'
 
     return dict
 
 #----------------------------------------------------------------------------
 def flag_calls(func):
     """Wrap a function to detect and flag when it gets called.
 
     This is a decorator which takes a function and wraps it in a function with
     a 'called' attribute. wrapper.called is initialized to False.
 
     The wrapper.called attribute is set to False right before each call to the
     wrapped function, so if the call fails it remains False.  After the call
     completes, wrapper.called is set to True and the output is returned.
 
     Testing for truth in wrapper.called allows you to determine if a call to
     func() was attempted and succeeded."""
 
     def wrapper(*args,**kw):
         wrapper.called = False
         out = func(*args,**kw)
         wrapper.called = True
         return out
 
     wrapper.called = False
     wrapper.__doc__ = func.__doc__
     return wrapper
 
 #----------------------------------------------------------------------------
 def dhook_wrap(func,*a,**k):
     """Wrap a function call in a sys.displayhook controller.
 
     Returns a wrapper around func which calls func, with all its arguments and
     keywords unmodified, using the default sys.displayhook.  Since IPython
     modifies sys.displayhook, it breaks the behavior of certain systems that
     rely on the default behavior, notably doctest.
     """
 
     def f(*a,**k):
 
         dhook_s = sys.displayhook
         sys.displayhook = sys.__displayhook__
         try:
             out = func(*a,**k)
         finally:
             sys.displayhook = dhook_s
 
         return out
 
     f.__doc__ = func.__doc__
     return f
 
 #----------------------------------------------------------------------------
 def doctest_reload():
     """Properly reload doctest to reuse it interactively.
 
     This routine:
 
       - reloads doctest
 
       - resets its global 'master' attribute to None, so that multiple uses of
       the module interactively don't produce cumulative reports.
 
       - Monkeypatches its core test runner method to protect it from IPython's
       modified displayhook.  Doctest expects the default displayhook behavior
       deep down, so our modification breaks it completely.  For this reason, a
       hard monkeypatch seems like a reasonable solution rather than asking
       users to manually use a different doctest runner when under IPython."""
 
     import doctest
     reload(doctest)
     doctest.master=None
 
     try:
         doctest.DocTestRunner
     except AttributeError:
         # This is only for python 2.3 compatibility, remove once we move to
         # 2.4 only.
         pass
     else:
         doctest.DocTestRunner.run = dhook_wrap(doctest.DocTestRunner.run)
 
 #----------------------------------------------------------------------------
 class HomeDirError(Error):
     pass
 
 def get_home_dir():
     """Return the closest possible equivalent to a 'home' directory.
 
     We first try $HOME.  Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
 
     Currently only Posix and NT are implemented, a HomeDirError exception is
     raised for all other OSes. """
 
     isdir = os.path.isdir
     env = os.environ
 
     # first, check py2exe distribution root directory for _ipython.
     # This overrides all. Normally does not exist.
 
     if '\\library.zip\\' in IPython.__file__.lower():
         root, rest = IPython.__file__.lower().split('library.zip')
         if isdir(root + '_ipython'):
             os.environ["IPYKITROOT"] = root.rstrip('\\')
             return root
 
     try:
         homedir = env['HOME']
         if not isdir(homedir):
             # in case a user stuck some string which does NOT resolve to a
             # valid path, it's as good as if we hadn't foud it
             raise KeyError
         return homedir
     except KeyError:
         if os.name == 'posix':
             raise HomeDirError,'undefined $HOME, IPython can not proceed.'
         elif os.name == 'nt':
             # For some strange reason, win9x returns 'nt' for os.name.
             try:
                 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
                 if not isdir(homedir):
                     homedir = os.path.join(env['USERPROFILE'])
                     if not isdir(homedir):
                         raise HomeDirError
                 return homedir
             except:
                 try:
                     # Use the registry to get the 'My Documents' folder.
                     import _winreg as wreg
                     key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
                                        "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
                     homedir = wreg.QueryValueEx(key,'Personal')[0]
                     key.Close()
                     if not isdir(homedir):
                         e = ('Invalid "Personal" folder registry key '
                              'typically "My Documents".\n'
                              'Value: %s\n'
                              'This is not a valid directory on your system.' %
                              homedir)
                         raise HomeDirError(e)
                     return homedir
                 except HomeDirError:
                     raise
                 except:
                     return 'C:\\'
         elif os.name == 'dos':
             # Desperate, may do absurd things in classic MacOS. May work under DOS.
             return 'C:\\'
         else:
             raise HomeDirError,'support for your operating system not implemented.'
 
+
+def get_ipython_dir():
+    """Get the IPython directory for this platform and user.
+    
+    This uses the logic in `get_home_dir` to find the home directory
+    and the adds either .ipython or _ipython to the end of the path.
+    """
+    if os.name == 'posix':
+         ipdir_def = '.ipython'
+    else:
+         ipdir_def = '_ipython'
+    home_dir = get_home_dir()
+    ipdir = os.path.abspath(os.environ.get('IPYTHONDIR',
+                                           os.path.join(home_dir,ipdir_def)))
+    return ipdir
+
+def get_security_dir():
+    """Get the IPython security directory.
+    
+    This directory is the default location for all security related files,
+    including SSL/TLS certificates and FURL files.
+    
+    If the directory does not exist, it is created with 0700 permissions.
+    If it exists, permissions are set to 0700.
+    """
+    security_dir = os.path.join(get_ipython_dir(), 'security')
+    if not os.path.isdir(security_dir):
+        os.mkdir(security_dir, 0700)
+    else:
+        os.chmod(security_dir, 0700)
+    return security_dir
+        
 #****************************************************************************
 # strings and text
 
 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)
 
 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])
 
 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 make_quoted_expr(s):
     """Return string s in appropriate quotes, using raw string if possible.
 
     Effectively this turns string: cd \ao\ao\
     to: r"cd \ao\ao\_"[:-1]
 
     Note the use of raw string and padding at the end to allow trailing backslash.
 
     """
 
     tail = ''
     tailpadding = ''
     raw  = ''
     if "\\" in s:
         raw = 'r'
         if s.endswith('\\'):
             tail = '[:-1]'
             tailpadding = '_'
     if '"' not in s:
         quote = '"'
     elif "'" not in s:
         quote = "'"
     elif '"""' not in s and not s.endswith('"'):
         quote = '"""'
     elif "'''" not in s and not s.endswith("'"):
         quote = "'''"
     else:
         # give up, backslash-escaped string will do
         return '"%s"' % esc_quotes(s)
     res = raw + quote + s + tailpadding + quote + tail
     return res
 
 
 #----------------------------------------------------------------------------
 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
     """Take multiple lines of input.
 
     A list with each line of input as a separate element is returned when a
     termination string is entered (defaults to a single '.'). Input can also
     terminate via EOF (^D in Unix, ^Z-RET in Windows).
 
     Lines of input which end in \\ are joined into single entries (and a
     secondary continuation prompt is issued as long as the user terminates
     lines with \\). This allows entering very long strings which are still
     meant to be treated as single entities.
     """
 
     try:
         if header:
             header += '\n'
         lines = [raw_input(header + ps1)]
     except EOFError:
         return []
     terminate = [terminate_str]
     try:
         while lines[-1:] != terminate:
             new_line = raw_input(ps1)
             while new_line.endswith('\\'):
                 new_line = new_line[:-1] + raw_input(ps2)
             lines.append(new_line)
 
         return lines[:-1]  # don't return the termination command
     except EOFError:
         print
         return lines
 
 #----------------------------------------------------------------------------
 def raw_input_ext(prompt='',  ps2='... '):
     """Similar to raw_input(), but accepts extended lines if input ends with \\."""
 
     line = raw_input(prompt)
     while line.endswith('\\'):
         line = line[:-1] + raw_input(ps2)
     return line
 
 #----------------------------------------------------------------------------
 def ask_yes_no(prompt,default=None):
     """Asks a question and returns a boolean (y/n) answer.
 
     If default is given (one of 'y','n'), it is used if the user input is
     empty. Otherwise the question is repeated until an answer is given.
 
     An EOF is treated as the default answer.  If there is no default, an
     exception is raised to prevent infinite loops.
 
     Valid answers are: y/yes/n/no (match is not case sensitive)."""
 
     answers = {'y':True,'n':False,'yes':True,'no':False}
     ans = None
     while ans not in answers.keys():
         try:
             ans = raw_input(prompt+' ').lower()
             if not ans:  # response was an empty string
                 ans = default
         except KeyboardInterrupt:
             pass
         except EOFError:
             if default in answers.keys():
                 ans = default
                 print
             else:
                 raise
 
     return answers[ans]
 
 #----------------------------------------------------------------------------
 def marquee(txt='',width=78,mark='*'):
     """Return the input string centered in a 'marquee'."""
     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)
 
 #----------------------------------------------------------------------------
 class EvalDict:
     """
     Emulate a dict which evaluates its contents in the caller's frame.
 
     Usage:
     >>> number = 19
 
     >>> text = "python"
 
     >>> print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
     Python 2.1 rules!
     """
 
     # This version is due to [e-mail] on c.l.py, and is basically a
     # modified (shorter) version of:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
     # Skip Montanaro ([e-mail]).
 
     def __getitem__(self, name):
         frame = sys._getframe(1)
         return eval(name, frame.f_globals, frame.f_locals)
 
 EvalString = EvalDict  # for backwards compatibility
 #----------------------------------------------------------------------------
 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 type(words) in StringTypes:
         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 type(indata) in StringTypes:
         return [qw(indata)]
     else:
         return qw(indata)
 
 #-----------------------------------------------------------------------------
 def list_strings(arg):
     """Always return a list of strings, given a string or list of strings
     as input."""
 
     if type(arg) in StringTypes: return [arg]
     else: return arg
 
 #----------------------------------------------------------------------------
 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(str,nspaces=4,ntabs=0):
     """Indent a string a given number of spaces or tabstops.
 
     indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
     """
     if str is None:
         return
     ind = '\t'*ntabs+' '*nspaces
     outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
     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 get_pager_cmd(pager_cmd = None):
     """Return a pager command.
 
     Makes some attempts at finding an OS-correct one."""
 
     if os.name == 'posix':
         default_pager_cmd = 'less -r'  # -r for color control sequences
     elif os.name in ['nt','dos']:
         default_pager_cmd = 'type'
 
     if pager_cmd is None:
         try:
             pager_cmd = os.environ['PAGER']
         except:
             pager_cmd = default_pager_cmd
     return pager_cmd
 
 #-----------------------------------------------------------------------------
 def get_pager_start(pager,start):
     """Return the string for paging files with an offset.
 
     This is the '+N' argument which less and more (under Unix) accept.
     """
 
     if pager in ['less','more']:
         if start:
             start_string = '+' + str(start)
         else:
             start_string = ''
     else:
         start_string = ''
     return start_string
 
 #----------------------------------------------------------------------------
 # (X)emacs on W32 doesn't like to be bypassed with msvcrt.getch()
 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
     import msvcrt
     def page_more():
         """ Smart pausing between pages
 
         @return:    True if need print more lines, False if quit
         """
         Term.cout.write('---Return to continue, q to quit--- ')
         ans = msvcrt.getch()
         if ans in ("q", "Q"):
             result = False
         else:
             result = True
         Term.cout.write("\b"*37 + " "*37 + "\b"*37)
         return result
 else:
     def page_more():
         ans = raw_input('---Return to continue, q to quit--- ')
         if ans.lower().startswith('q'):
             return False
         else:
             return True
 
 esc_re = re.compile(r"(\x1b[^m]+m)")
 
 def page_dumb(strng,start=0,screen_lines=25):
     """Very dumb 'pager' in Python, for when nothing else works.
 
     Only moves forward, same interface as page(), except for pager_cmd and
     mode."""
 
     out_ln  = strng.splitlines()[start:]
     screens = chop(out_ln,screen_lines-1)
     if len(screens) == 1:
         print >>Term.cout, os.linesep.join(screens[0])
     else:
         last_escape = ""
         for scr in screens[0:-1]:
             hunk = os.linesep.join(scr)
             print >>Term.cout, last_escape + hunk
             if not page_more():
                 return
             esc_list = esc_re.findall(hunk)
             if len(esc_list) > 0:
                 last_escape = esc_list[-1]
         print >>Term.cout, last_escape + os.linesep.join(screens[-1])
 
 #----------------------------------------------------------------------------
 def page(strng,start=0,screen_lines=0,pager_cmd = None):
     """Print a string, piping through a pager after a certain length.
 
     The screen_lines parameter specifies the number of *usable* lines of your
     terminal screen (total lines minus lines you need to reserve to show other
     information).
 
     If you set screen_lines to a number <=0, page() will try to auto-determine
     your screen size and will only use up to (screen_size+screen_lines) for
     printing, paging after that. That is, if you want auto-detection but need
     to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
     auto-detection without any lines reserved simply use screen_lines = 0.
 
     If a string won't fit in the allowed lines, it is sent through the
     specified pager command. If none given, look for PAGER in the environment,
     and ultimately default to less.
 
     If no system pager works, the string is sent through a 'dumb pager'
     written in python, very simplistic.
     """
 
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0,start)
 
     # first, try the hook
     ip = IPython.ipapi.get()
     if ip:
         try:
             ip.IP.hooks.show_in_pager(strng)
             return
         except IPython.ipapi.TryNext:
             pass
 
     # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
     TERM = os.environ.get('TERM','dumb')
     if TERM in ['dumb','emacs'] and os.name != 'nt':
         print strng
         return
     # chop off the topmost part of the string we don't want to see
     str_lines = strng.split(os.linesep)[start:]
     str_toprint = os.linesep.join(str_lines)
     num_newlines = len(str_lines)
     len_str = len(str_toprint)
 
     # Dumb heuristics to guesstimate number of on-screen lines the string
     # takes.  Very basic, but good enough for docstrings in reasonable
     # terminals. If someone later feels like refining it, it's not hard.
     numlines = max(num_newlines,int(len_str/80)+1)
 
     if os.name == "nt":
         screen_lines_def = get_console_size(defaulty=25)[1]
     else:
         screen_lines_def = 25 # default value if we can't auto-determine
 
     # auto-determine screen size
     if screen_lines <= 0:
         if TERM=='xterm':
             use_curses = USE_CURSES
         else:
             # curses causes problems on many terminals other than xterm.
             use_curses = False
         if use_curses:
             # There is a bug in curses, where *sometimes* it fails to properly
             # initialize, and then after the endwin() call is made, the
             # terminal is left in an unusable state.  Rather than trying to
             # check everytime for this (by requesting and comparing termios
             # flags each time), we just save the initial terminal state and
             # unconditionally reset it every time.  It's cheaper than making
             # the checks.
             term_flags = termios.tcgetattr(sys.stdout)
             scr = curses.initscr()
             screen_lines_real,screen_cols = scr.getmaxyx()
             curses.endwin()
             # Restore terminal state in case endwin() didn't.
             termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
             # Now we have what we needed: the screen size in rows/columns
             screen_lines += screen_lines_real
             #print '***Screen size:',screen_lines_real,'lines x',\
             #screen_cols,'columns.' # dbg
         else:
             screen_lines += screen_lines_def
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :
         #print '*** normal print'  # dbg
         print >>Term.cout, str_toprint
     else:
         # Try to open pager and default to internal one if that fails.
         # All failure modes are tagged as 'retval=1', to match the return
         # value of a failed system command.  If any intermediate attempt
         # sets retval to 1, at the end we resort to our own page_dumb() pager.
         pager_cmd = get_pager_cmd(pager_cmd)
         pager_cmd += ' ' + get_pager_start(pager_cmd,start)
         if os.name == 'nt':
             if pager_cmd.startswith('type'):
                 # The default WinXP 'type' command is failing on complex strings.
                 retval = 1
             else:
                 tmpname = tempfile.mktemp('.txt')
                 tmpfile = file(tmpname,'wt')
                 tmpfile.write(strng)
                 tmpfile.close()
                 cmd = "%s < %s" % (pager_cmd,tmpname)
                 if os.system(cmd):
                   retval = 1
                 else:
                   retval = None
                 os.remove(tmpname)
         else:
             try:
                 retval = None
                 # if I use popen4, things hang. No idea why.
                 #pager,shell_out = os.popen4(pager_cmd)
                 pager = os.popen(pager_cmd,'w')
                 pager.write(strng)
                 pager.close()
                 retval = pager.close()  # success returns None
             except IOError,msg:  # broken pipe when user quits
                 if msg.args == (32,'Broken pipe'):
                     retval = None
                 else:
                     retval = 1
             except OSError:
                 # Other strange problems, sometimes seen in Win2k/cygwin
                 retval = 1
         if retval is not None:
             page_dumb(strng,screen_lines=screen_lines)
 
 #----------------------------------------------------------------------------
 def page_file(fname,start = 0, pager_cmd = None):
     """Page a file, using an optional pager command and starting line.
     """
 
     pager_cmd = get_pager_cmd(pager_cmd)
     pager_cmd += ' ' + get_pager_start(pager_cmd,start)
 
     try:
         if os.environ['TERM'] in ['emacs','dumb']:
             raise EnvironmentError
         xsys(pager_cmd + ' ' + fname)
     except:
         try:
             if start > 0:
                 start -= 1
             page(open(fname).read(),start)
         except:
             print 'Unable to show file',`fname`
 
 
 #----------------------------------------------------------------------------
 def snip_print(str,width = 75,print_full = 0,header = ''):
     """Print a string snipping the midsection to fit in width.
 
     print_full: mode control:
       - 0: only snip long strings
       - 1: send to page() directly.
       - 2: snip long strings and ask for full length viewing with page()
     Return 1 if snipping was necessary, 0 otherwise."""
 
     if print_full == 1:
         page(header+str)
         return 0
 
     print header,
     if len(str) < width:
         print str
         snip = 0
     else:
         whalf = int((width -5)/2)
         print str[:whalf] + ' <...> ' + str[-whalf:]
         snip = 1
     if snip and print_full == 2:
         if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
             page(str)
     return snip
 
 #****************************************************************************
 # lists, dicts and structures
 
 def belong(candidates,checklist):
     """Check whether a list of items appear in a given list of options.
 
     Returns a list of 1 and 0, one for each candidate given."""
 
     return [x in checklist for x in candidates]
 
 #----------------------------------------------------------------------------
 def uniq_stable(elems):
     """uniq_stable(elems) -> list
 
     Return from an iterable, a list of all the unique elements in the input,
     but maintaining the order in which they first appear.
 
     A naive solution to this problem which just makes a dictionary with the
     elements as keys fails to respect the stability condition, since
     dictionaries are unsorted by nature.
 
     Note: All elements in the input must be valid dictionary keys for this
     routine to work, as it internally uses a dictionary for efficiency
     reasons."""
 
     unique = []
     unique_dict = {}
     for nn in elems:
         if nn not in unique_dict:
             unique.append(nn)
             unique_dict[nn] = None
     return unique
 
 #----------------------------------------------------------------------------
 class NLprinter:
     """Print an arbitrarily nested list, indicating index numbers.
 
     An instance of this class called nlprint is available and callable as a
     function.
 
     nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
     and using 'sep' to separate the index from the value. """
 
     def __init__(self):
         self.depth = 0
 
     def __call__(self,lst,pos='',**kw):
         """Prints the nested list numbering levels."""
         kw.setdefault('indent',' ')
         kw.setdefault('sep',': ')
         kw.setdefault('start',0)
         kw.setdefault('stop',len(lst))
         # we need to remove start and stop from kw so they don't propagate
         # into a recursive call for a nested list.
         start = kw['start']; del kw['start']
         stop = kw['stop']; del kw['stop']
         if self.depth == 0 and 'header' in kw.keys():
             print kw['header']
 
         for idx in range(start,stop):
             elem = lst[idx]
             if type(elem)==type([]):
                 self.depth += 1
                 self.__call__(elem,itpl('$pos$idx,'),**kw)
                 self.depth -= 1
             else:
                 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
 
 nlprint = NLprinter()
 #----------------------------------------------------------------------------
 def all_belong(candidates,checklist):
     """Check whether a list of items ALL appear in a given list of options.
 
     Returns a single 1 or 0 value."""
 
     return 1-(0 in [x in checklist for x in candidates])
 
 #----------------------------------------------------------------------------
 def sort_compare(lst1,lst2,inplace = 1):
     """Sort and compare two lists.
 
     By default it does it in place, thus modifying the lists. Use inplace = 0
     to avoid that (at the cost of temporary copy creation)."""
     if not inplace:
         lst1 = lst1[:]
         lst2 = lst2[:]
     lst1.sort(); lst2.sort()
     return lst1 == lst2
 
 #----------------------------------------------------------------------------
 def list2dict(lst):
     """Takes a list of (key,value) pairs and turns it into a dict."""
 
     dic = {}
     for k,v in lst: dic[k] = v
     return dic
 
 #----------------------------------------------------------------------------
 def list2dict2(lst,default=''):
     """Takes a list and turns it into a dict.
     Much slower than list2dict, but more versatile. This version can take
     lists with sublists of arbitrary length (including sclars)."""
 
     dic = {}
     for elem in lst:
         if type(elem) in (types.ListType,types.TupleType):
             size = len(elem)
             if  size == 0:
                 pass
             elif size == 1:
                 dic[elem] = default
             else:
                 k,v = elem[0], elem[1:]
                 if len(v) == 1: v = v[0]
                 dic[k] = v
         else:
             dic[elem] = default
     return dic
 
 #----------------------------------------------------------------------------
 def flatten(seq):
     """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
 
     return [x for subseq in seq for x in subseq]
 
 #----------------------------------------------------------------------------
 def get_slice(seq,start=0,stop=None,step=1):
     """Get a slice of a sequence with variable step. Specify start,stop,step."""
     if stop == None:
         stop = len(seq)
     item = lambda i: seq[i]
     return map(item,xrange(start,stop,step))
 
 #----------------------------------------------------------------------------
 def chop(seq,size):
     """Chop a sequence into chunks of the given size."""
     chunk = lambda i: seq[i:i+size]
     return map(chunk,xrange(0,len(seq),size))
 
 #----------------------------------------------------------------------------
 # with is a keyword as of python 2.5, so this function is renamed to withobj
 # from its old 'with' name.
 def with_obj(object, **args):
     """Set multiple attributes for an object, similar to Pascal's with.
 
     Example:
     with_obj(jim,
              born = 1960,
              haircolour = 'Brown',
              eyecolour = 'Green')
 
     Credit: Greg Ewing, in
     http://mail.python.org/pipermail/python-list/2001-May/040703.html.
 
     NOTE: up until IPython 0.7.2, this was called simply 'with', but 'with'
     has become a keyword for Python 2.5, so we had to rename it."""
 
     object.__dict__.update(args)
 
 #----------------------------------------------------------------------------
 def setattr_list(obj,alist,nspace = None):
     """Set a list of attributes for an object taken from a namespace.
 
     setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
     alist with their values taken from nspace, which must be a dict (something
     like locals() will often do) If nspace isn't given, locals() of the
     *caller* is used, so in most cases you can omit it.
 
     Note that alist can be given as a string, which will be automatically
     split into a list on whitespace. If given as a list, it must be a list of
     *strings* (the variable names themselves), not of variables."""
 
     # this grabs the local variables from the *previous* call frame -- that is
     # the locals from the function that called setattr_list().
     # - snipped from weave.inline()
     if nspace is None:
         call_frame = sys._getframe().f_back
         nspace = call_frame.f_locals
 
     if type(alist) in StringTypes:
         alist = alist.split()
     for attr in alist:
         val = eval(attr,nspace)
         setattr(obj,attr,val)
 
 #----------------------------------------------------------------------------
 def getattr_list(obj,alist,*args):
     """getattr_list(obj,alist[, default]) -> attribute list.
 
     Get a list of named attributes for an object. When a default argument is
     given, it is returned when the attribute doesn't exist; without it, an
     exception is raised in that case.
 
     Note that alist can be given as a string, which will be automatically
     split into a list on whitespace. If given as a list, it must be a list of
     *strings* (the variable names themselves), not of variables."""
 
     if type(alist) in StringTypes:
         alist = alist.split()
     if args:
         if len(args)==1:
             default = args[0]
             return map(lambda attr: getattr(obj,attr,default),alist)
         else:
             raise ValueError,'getattr_list() takes only one optional argument'
     else:
         return map(lambda attr: getattr(obj,attr),alist)
 
 #----------------------------------------------------------------------------
 def map_method(method,object_list,*argseq,**kw):
     """map_method(method,object_list,*args,**kw) -> list
 
     Return a list of the results of applying the methods to the items of the
     argument sequence(s).  If more than one sequence is given, the method is
     called with an argument list consisting of the corresponding item of each
     sequence. All sequences must be of the same length.
 
     Keyword arguments are passed verbatim to all objects called.
 
     This is Python code, so it's not nearly as fast as the builtin map()."""
 
     out_list = []
     idx = 0
     for object in object_list:
         try:
             handler = getattr(object, method)
         except AttributeError:
             out_list.append(None)
         else:
             if argseq:
                 args = map(lambda lst:lst[idx],argseq)
                 #print 'ob',object,'hand',handler,'ar',args # dbg
                 out_list.append(handler(args,**kw))
             else:
                 out_list.append(handler(**kw))
         idx += 1
     return out_list
 
 #----------------------------------------------------------------------------
 def get_class_members(cls):
     ret = dir(cls)
     if hasattr(cls,'__bases__'):
         for base in cls.__bases__:
             ret.extend(get_class_members(base))
     return ret
 
 #----------------------------------------------------------------------------
 def dir2(obj):
     """dir2(obj) -> list of strings
 
     Extended version of the Python builtin dir(), which does a few extra
     checks, and supports common objects with unusual internals that confuse
     dir(), such as Traits and PyCrust.
 
     This version is guaranteed to return only a list of true strings, whereas
     dir() returns anything that objects inject into themselves, even if they
     are later not really valid for attribute access (many extension libraries
     have such bugs).
     """
 
     # Start building the attribute list via dir(), and then complete it
     # with a few extra special-purpose calls.
     words = dir(obj)
 
     if hasattr(obj,'__class__'):
         words.append('__class__')
         words.extend(get_class_members(obj.__class__))
     #if '__base__' in words: 1/0
 
     # Some libraries (such as traits) may introduce duplicates, we want to
     # track and clean this up if it happens
     may_have_dupes = False
 
     # this is the 'dir' function for objects with Enthought's traits
     if hasattr(obj, 'trait_names'):
         try:
             words.extend(obj.trait_names())
             may_have_dupes = True
         except TypeError:
             # This will happen if `obj` is a class and not an instance.
             pass
 
     # Support for PyCrust-style _getAttributeNames magic method.
     if hasattr(obj, '_getAttributeNames'):
         try:
             words.extend(obj._getAttributeNames())
             may_have_dupes = True
         except TypeError:
             # `obj` is a class and not an instance.  Ignore
             # this error.
             pass
 
     if may_have_dupes:
         # eliminate possible duplicates, as some traits may also
         # appear as normal attributes in the dir() call.
         words = list(set(words))
         words.sort()
 
     # filter out non-string attributes which may be stuffed by dir() calls
     # and poor coding in third-party modules
     return [w for w in words if isinstance(w, basestring)]
 
 #----------------------------------------------------------------------------
 def import_fail_info(mod_name,fns=None):
     """Inform load failure for a module."""
 
     if fns == None:
         warn("Loading of %s failed.\n" % (mod_name,))
     else:
         warn("Loading of %s from %s failed.\n" % (fns,mod_name))
 
 #----------------------------------------------------------------------------
 # Proposed popitem() extension, written as a method
 
 
 class NotGiven: pass
 
 def popkey(dct,key,default=NotGiven):
     """Return dct[key] and delete dct[key].
 
     If default is given, return it if dct[key] doesn't exist, otherwise raise
     KeyError.  """
 
     try:
         val = dct[key]
     except KeyError:
         if default is NotGiven:
             raise
         else:
             return default
     else:
         del dct[key]
         return val
 
 def wrap_deprecated(func, suggest = '<nothing>'):
     def newFunc(*args, **kwargs):
         warnings.warn("Call to deprecated function %s, use %s instead" %
                       ( func.__name__, suggest),
                       category=DeprecationWarning,
                       stacklevel = 2)
         return func(*args, **kwargs)
     return newFunc
 
 
 def _num_cpus_unix():
     """Return the number of active CPUs on a Unix system."""
     return os.sysconf("SC_NPROCESSORS_ONLN")
 
 
 def _num_cpus_darwin():
     """Return the number of active CPUs on a Darwin system."""
     p = subprocess.Popen(['sysctl','-n','hw.ncpu'],stdout=subprocess.PIPE)
     return p.stdout.read()
 
 
 def _num_cpus_windows():
     """Return the number of active CPUs on a Windows system."""
     return os.environ.get("NUMBER_OF_PROCESSORS")
 
 
 def num_cpus():
    """Return the effective number of CPUs in the system as an integer.
 
    This cross-platform function makes an attempt at finding the total number of
    available CPUs in the system, as returned by various underlying system and
    python calls.
 
    If it can't find a sensible answer, it returns 1 (though an error *may* make
    it return a large positive number that's actually incorrect).
    """
 
    # Many thanks to the Parallel Python project (http://www.parallelpython.com)
    # for the names of the keys we needed to look up for this function.  This
    # code was inspired by their equivalent function.
 
    ncpufuncs = {'Linux':_num_cpus_unix,
                 'Darwin':_num_cpus_darwin,
                 'Windows':_num_cpus_windows,
                 # On Vista, python < 2.5.2 has a bug and returns 'Microsoft'
                 # See http://bugs.python.org/issue1082 for details.
                 'Microsoft':_num_cpus_windows,
                 }
 
    ncpufunc = ncpufuncs.get(platform.system(),
                             # default to unix version (Solaris, AIX, etc)
                             _num_cpus_unix)
 
    try:
        ncpus = max(1,int(ncpufunc()))
    except:
        ncpus = 1
    return ncpus
 
 #*************************** end of file <genutils.py> **********************

IPython/history.py

@@ -1,272 +1,281
 # -*- coding: utf-8 -*-
 
 """ History related magics and functionality """
 
 # Stdlib imports
 import fnmatch
 import os
 
 # IPython imports
 from IPython.genutils import Term, ask_yes_no
+import IPython.ipapi
 
 def magic_history(self, parameter_s = ''):
     """Print input history (_i<n> variables), with most recent last.
     
     %history       -> print at most 40 inputs (some may be multi-line)\\
     %history n     -> print at most n inputs\\
     %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
     
     Each input's number <n> is shown, and is accessible as the
     automatically generated variable _i<n>.  Multi-line statements are
     printed starting at a new line for easy copy/paste.
     
 
     Options:
 
       -n: do NOT print line numbers. This is useful if you want to get a
       printout of many lines which can be directly pasted into a text
       editor.
 
       This feature is only available if numbered prompts are in use.
 
       -t: (default) print the 'translated' history, as IPython understands it.
       IPython filters your input and converts it all into valid Python source
       before executing it (things like magics or aliases are turned into
       function calls, for example). With this option, you'll see the native
       history instead of the user-entered version: '%cd /' will be seen as
       '_ip.magic("%cd /")' instead of '%cd /'.
       
       -r: print the 'raw' history, i.e. the actual commands you typed.
       
       -g: treat the arg as a pattern to grep for in (full) history.
       This includes the "shadow history" (almost all commands ever written).
       Use '%hist -g' to show full shadow history (may be very long).
       In shadow history, every index nuwber starts with 0.
 
       -f FILENAME: instead of printing the output to the screen, redirect it to
        the given file.  The file is always overwritten, though IPython asks for
        confirmation first if it already exists.
       
 
     """
 
     ip = self.api
     shell = self.shell
     if not shell.outputcache.do_full_cache:
         print 'This feature is only available if numbered prompts are in use.'
         return
     opts,args = self.parse_options(parameter_s,'gntsrf:',mode='list')
 
     # Check if output to specific file was requested.
     try:
         outfname = opts['f']
     except KeyError:
         outfile = Term.cout
         # We don't want to close stdout at the end!
         close_at_end = False
     else:
         if os.path.exists(outfname):
             ans = ask_yes_no("File %r exists. Overwrite?" % outfname)
             if not ans:
                 print 'Aborting.'
                 return
             else:
                 outfile = open(outfname,'w')
                 close_at_end = True
                 
 
     if opts.has_key('t'):
         input_hist = shell.input_hist
     elif opts.has_key('r'):
         input_hist = shell.input_hist_raw
     else:
         input_hist = shell.input_hist
         
     
     default_length = 40
     pattern = None
     if opts.has_key('g'):
         init = 1
         final = len(input_hist)
         parts = parameter_s.split(None,1)
         if len(parts) == 1:
             parts += '*'
         head, pattern = parts
         pattern = "*" + pattern + "*"
     elif len(args) == 0:
         final = len(input_hist)
         init = max(1,final-default_length)
     elif len(args) == 1:
         final = len(input_hist)
         init = max(1,final-int(args[0]))
     elif len(args) == 2:
         init,final = map(int,args)
     else:
         warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
         print self.magic_hist.__doc__
         return
     width = len(str(final))
     line_sep = ['','\n']
     print_nums = not opts.has_key('n')
     
     found = False
     if pattern is not None:
         sh = ip.IP.shadowhist.all()
         for idx, s in sh:
             if fnmatch.fnmatch(s, pattern):
                 print "0%d: %s" %(idx, s)
                 found = True
     
     if found:
         print "==="
         print "shadow history ends, fetch by %rep <number> (must start with 0)"
         print "=== start of normal history ==="
         
     for in_num in range(init,final):        
         inline = input_hist[in_num]
         if pattern is not None and not fnmatch.fnmatch(inline, pattern):
             continue
             
         multiline = int(inline.count('\n') > 1)
         if print_nums:
             print >> outfile, \
                   '%s:%s' % (str(in_num).ljust(width),line_sep[multiline]),
         print >> outfile, inline,
 
     if close_at_end:
         outfile.close()
 
 
 
 def magic_hist(self, parameter_s=''):
     """Alternate name for %history."""
     return self.magic_history(parameter_s)
 
 
 
 def rep_f(self, arg):
     r""" Repeat a command, or get command to input line for editing
 
     - %rep (no arguments):
     
     Place a string version of last computation result (stored in the special '_'
     variable) to the next input prompt. Allows you to create elaborate command
     lines without using copy-paste::
     
         $ l = ["hei", "vaan"]       
         $ "".join(l)        
         ==> heivaan        
         $ %rep        
         $ heivaan_ <== cursor blinking    
     
     %rep 45
     
     Place history line 45 to next input prompt. Use %hist to find out the
     number.
     
     %rep 1-4 6-7 3
     
     Repeat the specified lines immediately. Input slice syntax is the same as
     in %macro and %save.
     
     %rep foo
     
     Place the most recent line that has the substring "foo" to next input.
     (e.g. 'svn ci -m foobar').
     
     """
     
     
     opts,args = self.parse_options(arg,'',mode='list')
     ip = self.api    
     if not args:
         ip.set_next_input(str(ip.user_ns["_"]))
         return
 
     if len(args) == 1 and not '-' in args[0]:
         arg = args[0]
         if len(arg) > 1 and arg.startswith('0'):
             # get from shadow hist
             num = int(arg[1:])
             line = self.shadowhist.get(num)
             ip.set_next_input(str(line))
             return
         try:
             num = int(args[0])
             ip.set_next_input(str(ip.IP.input_hist_raw[num]).rstrip())
             return
         except ValueError:
             pass
         
         for h in reversed(self.shell.input_hist_raw):
             if 'rep' in h:
                 continue
             if fnmatch.fnmatch(h,'*' + arg + '*'):
                 ip.set_next_input(str(h).rstrip())
                 return
         
 
     try:
         lines = self.extract_input_slices(args, True)
         print "lines",lines
         ip.runlines(lines)
     except ValueError:
         print "Not found in recent history:", args
         
 
 
 _sentinel = object()
 
 class ShadowHist:
     def __init__(self,db):
         # cmd => idx mapping
         self.curidx = 0
         self.db = db
+        self.disabled = False
     
     def inc_idx(self):
         idx = self.db.get('shadowhist_idx', 1)
         self.db['shadowhist_idx'] = idx + 1
         return idx
         
     def add(self, ent):
-        old = self.db.hget('shadowhist', ent, _sentinel)
-        if old is not _sentinel:
+        if self.disabled:
             return
-        newidx = self.inc_idx()
-        #print "new",newidx # dbg
-        self.db.hset('shadowhist',ent, newidx)
+        try:
+            old = self.db.hget('shadowhist', ent, _sentinel)
+            if old is not _sentinel:
+                return
+            newidx = self.inc_idx()
+            #print "new",newidx # dbg
+            self.db.hset('shadowhist',ent, newidx)
+        except:
+            IPython.ipapi.get().IP.showtraceback()
+            print "WARNING: disabling shadow history"
+            self.disabled = True
     
     def all(self):
         d = self.db.hdict('shadowhist')
         items = [(i,s) for (s,i) in d.items()]
         items.sort()
         return items
 
     def get(self, idx):
         all = self.all()
         
         for k, v in all:
             #print k,v
             if k == idx:
                 return v
 
 def test_shist():
     from IPython.Extensions import pickleshare
     db = pickleshare.PickleShareDB('~/shist')
     s = ShadowHist(db)
     s.add('hello')
     s.add('world')
     s.add('hello')
     s.add('hello')
     s.add('karhu')
     print "all",s.all()
     print s.get(2)
 
 def init_ipython(ip):
     ip.expose_magic("rep",rep_f)        
     ip.expose_magic("hist",magic_hist)            
     ip.expose_magic("history",magic_history)
 
     import ipy_completers
     ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
 #test_shist()

IPython/hooks.py

@@ -1,249 +1,252
 """hooks for IPython.
 
 In Python, it is possible to overwrite any method of any object if you really
 want to.  But IPython exposes a few 'hooks', methods which are _designed_ to
 be overwritten by users for customization purposes.  This module defines the
 default versions of all such hooks, which get used by IPython if not
 overridden by the user.
 
 hooks are simple functions, but they should be declared with 'self' as their
 first argument, because when activated they are registered into IPython as
 instance methods.  The self argument will be the IPython running instance
 itself, so hooks have full access to the entire IPython object.
 
 If you wish to define a new hook and activate it, you need to put the
 necessary code into a python file which can be either imported or execfile()'d
 from within your ipythonrc configuration.
 
 For example, suppose that you have a module called 'myiphooks' in your
 PYTHONPATH, which contains the following definition:
 
 import os
 import IPython.ipapi
 ip = IPython.ipapi.get()
 
 def calljed(self,filename, linenum):
     "My editor hook calls the jed editor directly."
     print "Calling my own editor, jed ..."
-    os.system('jed +%d %s' % (linenum,filename))
+    if os.system('jed +%d %s' % (linenum,filename)) != 0:
+        raise ipapi.TryNext()
 
 ip.set_hook('editor', calljed)
 
 You can then enable the functionality by doing 'import myiphooks'
 somewhere in your configuration files or ipython command line.
 
 $Id: hooks.py 2998 2008-01-31 10:06:04Z vivainio $"""
 
 #*****************************************************************************
 #       Copyright (C) 2005 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 IPython import Release
 from IPython import ipapi
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 __version__ = Release.version
 
 import os,bisect
 from genutils import Term,shell
 from pprint import PrettyPrinter
 
 # List here all the default hooks.  For now it's just the editor functions
 # but over time we'll move here all the public API for user-accessible things.
 # vds: >>
 __all__ = ['editor', 'fix_error_editor', 'synchronize_with_editor', 'result_display',
            'input_prefilter', 'shutdown_hook', 'late_startup_hook',
            'generate_prompt', 'generate_output_prompt','shell_hook',
            'show_in_pager','pre_prompt_hook', 'pre_runcode_hook']
 # vds: <<
 
 pformat = PrettyPrinter().pformat
 
 def editor(self,filename, linenum=None):
     """Open the default editor at the given filename and linenumber.
 
     This is IPython's default editor hook, you can use it as an example to
     write your own modified one.  To set your own editor function as the
     new editor hook, call ip.set_hook('editor',yourfunc)."""
 
     # IPython configures a default editor at startup by reading $EDITOR from
     # the environment, and falling back on vi (unix) or notepad (win32).
     editor = self.rc.editor
     
     # marker for at which line to open the file (for existing objects)
     if linenum is None or editor=='notepad':
         linemark = ''
     else:
         linemark = '+%d' % int(linenum)
     
     # Enclose in quotes if necessary and legal
     if ' ' in editor and os.path.isfile(editor) and editor[0] != '"':
         editor = '"%s"' % editor
         
     # Call the actual editor
-    os.system('%s %s %s' % (editor,linemark,filename))
+    if os.system('%s %s %s' % (editor,linemark,filename)) != 0:
+        raise ipapi.TryNext()
 
 import tempfile
 def fix_error_editor(self,filename,linenum,column,msg):
     """Open the editor at the given filename, linenumber, column and 
     show an error message. This is used for correcting syntax errors.
     The current implementation only has special support for the VIM editor,
     and falls back on the 'editor' hook if VIM is not used.
 
     Call ip.set_hook('fix_error_editor',youfunc) to use your own function,
     """
     def vim_quickfix_file():
         t = tempfile.NamedTemporaryFile()
         t.write('%s:%d:%d:%s\n' % (filename,linenum,column,msg))
         t.flush()
         return t
     if os.path.basename(self.rc.editor) != 'vim':
         self.hooks.editor(filename,linenum)
         return
     t = vim_quickfix_file()
     try:
-        os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name)
+        if os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name):
+            raise ipapi.TryNext()
     finally:
         t.close()
 
 # vds: >>
 def synchronize_with_editor(self, filename, linenum, column):
 	pass
 # vds: <<
 
 class CommandChainDispatcher:
     """ Dispatch calls to a chain of commands until some func can handle it
     
     Usage: instantiate, execute "add" to add commands (with optional
     priority), execute normally via f() calling mechanism.
     
     """
     def __init__(self,commands=None):
         if commands is None:
             self.chain = []
         else:
             self.chain = commands
             
             
     def __call__(self,*args, **kw):
         """ Command chain is called just like normal func. 
         
         This will call all funcs in chain with the same args as were given to this
         function, and return the result of first func that didn't raise
         TryNext """
         
         for prio,cmd in self.chain:
             #print "prio",prio,"cmd",cmd #dbg
             try:
                 ret = cmd(*args, **kw)
                 return ret
             except ipapi.TryNext, exc:
                 if exc.args or exc.kwargs:
                     args = exc.args
                     kw = exc.kwargs
         # if no function will accept it, raise TryNext up to the caller
         raise ipapi.TryNext
                 
     def __str__(self):
         return str(self.chain)
     
     def add(self, func, priority=0):
         """ Add a func to the cmd chain with given priority """
         bisect.insort(self.chain,(priority,func))
 
     def __iter__(self):
         """ Return all objects in chain.
         
         Handy if the objects are not callable.
         """
         return iter(self.chain)
     
 def result_display(self,arg):
     """ Default display hook.
     
     Called for displaying the result to the user.
     """
     
     if self.rc.pprint:
         out = pformat(arg)
         if '\n' in out:
             # So that multi-line strings line up with the left column of
             # the screen, instead of having the output prompt mess up
             # their first line.                
             Term.cout.write('\n')
         print >>Term.cout, out
     else:
         # By default, the interactive prompt uses repr() to display results,
         # so we should honor this.  Users who'd rather use a different
         # mechanism can easily override this hook.
         print >>Term.cout, repr(arg)
     # the default display hook doesn't manipulate the value to put in history
     return None 
 
 def input_prefilter(self,line):     
     """ Default input prefilter
     
     This returns the line as unchanged, so that the interpreter
     knows that nothing was done and proceeds with "classic" prefiltering
     (%magics, !shell commands etc.). 
     
     Note that leading whitespace is not passed to this hook. Prefilter
     can't alter indentation.
     
     """
     #print "attempt to rewrite",line #dbg
     return line
 
 def shutdown_hook(self):
     """ default shutdown hook
     
     Typically, shotdown hooks should raise TryNext so all shutdown ops are done
     """
     
     #print "default shutdown hook ok" # dbg
     return
 
 def late_startup_hook(self):
     """ Executed after ipython has been constructed and configured 
     
     """
     #print "default startup hook ok" # dbg
 
 def generate_prompt(self, is_continuation):
     """ calculate and return a string with the prompt to display """
     ip = self.api
     if is_continuation:
         return str(ip.IP.outputcache.prompt2)
     return str(ip.IP.outputcache.prompt1)
 
 def generate_output_prompt(self):
     ip = self.api
     return str(ip.IP.outputcache.prompt_out)
 
 def shell_hook(self,cmd):
     """ Run system/shell command a'la os.system() """
 
     shell(cmd, header=self.rc.system_header, verbose=self.rc.system_verbose)
 
 def show_in_pager(self,s):
     """ Run a string through pager """
     # raising TryNext here will use the default paging functionality
     raise ipapi.TryNext
 
 def pre_prompt_hook(self):
     """ Run before displaying the next prompt
     
     Use this e.g. to display output from asynchronous operations (in order 
     to not mess up text entry)   
     """
     
     return None
 
 def pre_runcode_hook(self):
     """ Executed before running the (prefiltered) code in IPython """
     return None
     
 

IPython/iplib.py

@@ -1,2686 +1,2695
 # -*- coding: utf-8 -*-
 """
 IPython -- An enhanced Interactive Python
 
 Requires Python 2.3 or newer.
 
 This file contains all the classes and helper functions specific to IPython.
 
 """
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
 #       Copyright (C) 2001-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.
 #
 # Note: this code originally subclassed code.InteractiveConsole from the
 # Python standard library.  Over time, all of that class has been copied
 # verbatim here for modifications which could not be accomplished by
 # subclassing.  At this point, there are no dependencies at all on the code
 # module anymore (it is not even imported).  The Python License (sec. 2)
 # allows for this, but it's always nice to acknowledge credit where credit is
 # due.
 #*****************************************************************************
 
 #****************************************************************************
 # Modules and globals
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % \
               ( Release.authors['Janko'] + Release.authors['Fernando'] )
 __license__ = Release.license
 __version__ = Release.version
 
 # Python standard modules
 import __main__
 import __builtin__
 import StringIO
 import bdb
 import cPickle as pickle
 import codeop
 import exceptions
 import glob
 import inspect
 import keyword
 import new
 import os
 import pydoc
 import re
 import shutil
 import string
 import sys
 import tempfile
 import traceback
 import types
 import warnings
 warnings.filterwarnings('ignore', r'.*sets module*')
 from sets import Set
 from pprint import pprint, pformat
 
 # IPython's own modules
 #import IPython
 from IPython import Debugger,OInspect,PyColorize,ultraTB
 from IPython.ColorANSI import ColorScheme,ColorSchemeTable  # too long names
 from IPython.Extensions import pickleshare
 from IPython.FakeModule import FakeModule
 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
 from IPython.Logger import Logger
 from IPython.Magic import Magic
 from IPython.Prompts import CachedOutput
 from IPython.ipstruct import Struct
 from IPython.background_jobs import BackgroundJobManager
 from IPython.usage import cmd_line_usage,interactive_usage
 from IPython.genutils import *
 from IPython.strdispatch import StrDispatch
 import IPython.ipapi
 import IPython.history
 import IPython.prefilter as prefilter
 import IPython.shadowns
 # Globals
 
 # store the builtin raw_input globally, and use this always, in case user code
 # overwrites it (like wx.py.PyShell does)
 raw_input_original = raw_input
 
 # compiled regexps for autoindent management
 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
 
 
 #****************************************************************************
 # Some utility function definitions
 
 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 softspace(file, newvalue):
     """Copied from code.py, to remove the dependency"""
 
     oldvalue = 0
     try:
         oldvalue = file.softspace
     except AttributeError:
         pass
     try:
         file.softspace = newvalue
     except (AttributeError, TypeError):
         # "attribute-less object" or "read-only attributes"
         pass
     return oldvalue
 
 
 #****************************************************************************
 # Local use exceptions
 class SpaceInInput(exceptions.Exception): pass
 
 
 #****************************************************************************
 # Local use classes
 class Bunch: pass
 
 class Undefined: pass
 
 class Quitter(object):
     """Simple class to handle exit, similar to Python 2.5's.
 
     It handles exiting in an ipython-safe manner, which the one in Python 2.5
     doesn't do (obviously, since it doesn't know about ipython)."""
     
     def __init__(self,shell,name):
         self.shell = shell
         self.name = name
         
     def __repr__(self):
         return 'Type %s() to exit.' % self.name
     __str__ = __repr__
 
     def __call__(self):
         self.shell.exit()
 
 class InputList(list):
     """Class to store user input.
 
     It's basically a list, but slices return a string instead of a list, thus
     allowing things like (assuming 'In' is an instance):
 
     exec In[4:7]
 
     or
 
     exec In[5:9] + In[14] + In[21:25]"""
 
     def __getslice__(self,i,j):
         return ''.join(list.__getslice__(self,i,j))
 
 class SyntaxTB(ultraTB.ListTB):
     """Extension which holds some state: the last exception value"""
 
     def __init__(self,color_scheme = 'NoColor'):
         ultraTB.ListTB.__init__(self,color_scheme)
         self.last_syntax_error = None
 
     def __call__(self, etype, value, elist):
         self.last_syntax_error = value
         ultraTB.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
 
 #****************************************************************************
 # Main IPython class
 
 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
 # until a full rewrite is made.  I've cleaned all cross-class uses of
 # attributes and methods, but too much user code out there relies on the
 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
 #
 # But at least now, all the pieces have been separated and we could, in
 # principle, stop using the mixin.  This will ease the transition to the
 # chainsaw branch.
 
 # For reference, the following is the list of 'self.foo' uses in the Magic
 # class as of 2005-12-28.  These are names we CAN'T use in the main ipython
 # class, to prevent clashes.
 
 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
 #  'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
 #  'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
 #  'self.value']
 
 class InteractiveShell(object,Magic):
     """An enhanced console for Python."""
 
     # class attribute to indicate whether the class supports threads or not.
     # Subclasses with thread support should override this as needed.
     isthreaded = False
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None,banner2='',
                  custom_exceptions=((),None),embedded=False):
 
         # log system
         self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
             
         # Job manager (for jobs run as background threads)
         self.jobs = BackgroundJobManager()
 
         # Store the actual shell's name
         self.name = name
         self.more = False
 
         # We need to know whether the instance is meant for embedding, since
         # global/local namespaces need to be handled differently in that case
         self.embedded = embedded
         if embedded:
             # Control variable so users can, from within the embedded instance,
             # permanently deactivate it.
             self.embedded_active = True
 
         # command compiler
         self.compile = codeop.CommandCompiler()
 
         # User input buffer
         self.buffer = []
 
         # Default name given in compilation of code
         self.filename = '<ipython console>'
 
         # Install our own quitter instead of the builtins.  For python2.3-2.4,
         # this brings in behavior like 2.5, and for 2.5 it's identical.
         __builtin__.exit = Quitter(self,'exit')
         __builtin__.quit = Quitter(self,'quit')
         
         # Make an empty namespace, which extension writers can rely on both
         # existing and NEVER being used by ipython itself.  This gives them a
         # convenient location for storing additional information and state
         # their extensions may require, without fear of collisions with other
         # ipython names that may develop later.
         self.meta = Struct()
 
         # Create the namespace where the user will operate.  user_ns is
         # normally the only one used, and it is passed to the exec calls as
         # the locals argument.  But we do carry a user_global_ns namespace
         # given as the exec 'globals' argument,  This is useful in embedding
         # situations where the ipython shell opens in a context where the
         # distinction between locals and globals is meaningful.  For
         # non-embedded contexts, it is just the same object as the user_ns dict.
 
         # FIXME. For some strange reason, __builtins__ is showing up at user
         # level as a dict instead of a module. This is a manual fix, but I
         # should really track down where the problem is coming from. Alex
         # Schmolck reported this problem first.
 
         # A useful post by Alex Martelli on this topic:
         # Re: inconsistent value from __builtins__
         # Von: Alex Martelli <[e-mail]>
         # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
         # Gruppen: comp.lang.python
 
         # Michael Hohn <[e-mail]> wrote:
         # > >>> print type(builtin_check.get_global_binding('__builtins__'))
         # > <type 'dict'>
         # > >>> print type(__builtins__)
         # > <type 'module'>
         # > Is this difference in return value intentional?
 
         # Well, it's documented that '__builtins__' can be either a dictionary
         # or a module, and it's been that way for a long time. Whether it's
         # intentional (or sensible), I don't know. In any case, the idea is
         # that if you need to access the built-in namespace directly, you
         # should start with "import __builtin__" (note, no 's') which will
         # definitely give you a module. Yeah, it's somewhat confusing:-(.
 
         # These routines return properly built dicts as needed by the rest of
         # the code, and can also be used by extension writers to generate
         # properly initialized namespaces.
         user_ns, user_global_ns = IPython.ipapi.make_user_namespaces(user_ns,
             user_global_ns)
 
         # Assign namespaces
         # This is the namespace where all normal user variables live
         self.user_ns = user_ns
         self.user_global_ns = user_global_ns
         # A namespace to keep track of internal data structures to prevent
         # them from cluttering user-visible stuff.  Will be updated later
         self.internal_ns = {}
 
         # Namespace of system aliases.  Each entry in the alias
         # table must be a 2-tuple of the form (N,name), where N is the number
         # of positional arguments of the alias.
         self.alias_table = {}
 
         # A table holding all the namespaces IPython deals with, so that
         # introspection facilities can search easily.
         self.ns_table = {'user':user_ns,
                          'user_global':user_global_ns,
                          'alias':self.alias_table,
                          'internal':self.internal_ns,
                          'builtin':__builtin__.__dict__
                          }
         # The user namespace MUST have a pointer to the shell itself.
         self.user_ns[name] = self
 
         # We need to insert into sys.modules something that looks like a
         # module but which accesses the IPython namespace, for shelve and
         # pickle to work interactively. Normally they rely on getting
         # everything out of __main__, but for embedding purposes each IPython
         # instance has its own private namespace, so we can't go shoving
         # everything into __main__.
 
         # note, however, that we should only do this for non-embedded
         # ipythons, which really mimic the __main__.__dict__ with their own
         # namespace.  Embedded instances, on the other hand, should not do
         # this because they need to manage the user local/global namespaces
         # only, but they live within a 'normal' __main__ (meaning, they
         # shouldn't overtake the execution environment of the script they're
         # embedded in).
 
         if not embedded:
             try:
                 main_name = self.user_ns['__name__']
             except KeyError:
                 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
             else:
                 #print "pickle hack in place"  # dbg
                 #print 'main_name:',main_name # dbg
                 sys.modules[main_name] = FakeModule(self.user_ns)
 
         # Now that FakeModule produces a real module, we've run into a nasty
         # problem: after script execution (via %run), the module where the user
         # code ran is deleted.  Now that this object is a true module (needed
         # so docetst and other tools work correctly), the Python module
         # teardown mechanism runs over it, and sets to None every variable
         # present in that module.  This means that later calls to functions
         # defined in the script (which have become interactively visible after
         # script exit) fail, because they hold references to objects that have
         # become overwritten into None.  The only solution I see right now is
         # to protect every FakeModule used by %run by holding an internal
         # reference to it.  This private list will be used for that.  The
         # %reset command will flush it as well.
         self._user_main_modules = []
 
         # List of input with multi-line handling.
         # Fill its zero entry, user counter starts at 1
         self.input_hist = InputList(['\n'])
         # This one will hold the 'raw' input history, without any
         # pre-processing.  This will allow users to retrieve the input just as
         # it was exactly typed in by the user, with %hist -r.
         self.input_hist_raw = InputList(['\n'])
 
         # list of visited directories
         try:
             self.dir_hist = [os.getcwd()]
         except OSError:
             self.dir_hist = []
 
         # dict of output history
         self.output_hist = {}
 
         # Get system encoding at startup time.  Certain terminals (like Emacs
         # under Win32 have it set to None, and we need to have a known valid
         # encoding to use in the raw_input() method
         try:
             self.stdin_encoding = sys.stdin.encoding or 'ascii'
         except AttributeError:
             self.stdin_encoding = 'ascii'
 
         # dict of things NOT to alias (keywords, builtins and some magics)
         no_alias = {}
         no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
         for key in keyword.kwlist + no_alias_magics:
             no_alias[key] = 1
         no_alias.update(__builtin__.__dict__)
         self.no_alias = no_alias
                 
         # make global variables for user access to these
         self.user_ns['_ih'] = self.input_hist
         self.user_ns['_oh'] = self.output_hist
         self.user_ns['_dh'] = self.dir_hist
 
         # user aliases to input and output histories
         self.user_ns['In']  = self.input_hist
         self.user_ns['Out'] = self.output_hist
 
         self.user_ns['_sh'] = IPython.shadowns
         # Object variable to store code object waiting execution.  This is
         # used mainly by the multithreaded shells, but it can come in handy in
         # other situations.  No need to use a Queue here, since it's a single
         # item which gets cleared once run.
         self.code_to_run = None
         
         # escapes for automatic behavior on the command line
         self.ESC_SHELL  = '!'
         self.ESC_SH_CAP = '!!'
         self.ESC_HELP   = '?'
         self.ESC_MAGIC  = '%'
         self.ESC_QUOTE  = ','
         self.ESC_QUOTE2 = ';'
         self.ESC_PAREN  = '/'
 
         # And their associated handlers
         self.esc_handlers = {self.ESC_PAREN  : self.handle_auto,
                              self.ESC_QUOTE  : self.handle_auto,
                              self.ESC_QUOTE2 : self.handle_auto,
                              self.ESC_MAGIC  : self.handle_magic,
                              self.ESC_HELP   : self.handle_help,
                              self.ESC_SHELL  : self.handle_shell_escape,
                              self.ESC_SH_CAP : self.handle_shell_escape,
                              }
 
         # class initializations
         Magic.__init__(self,self)
 
         # Python source parser/formatter for syntax highlighting
         pyformat = PyColorize.Parser().format
         self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
 
         # hooks holds pointers used for user-side customizations
         self.hooks = Struct()
         
         self.strdispatchers = {}
         
         # Set all default hooks, defined in the IPython.hooks module.
         hooks = IPython.hooks
         for hook_name in hooks.__all__:
             # default hooks have priority 100, i.e. low; user hooks should have
             # 0-100 priority
             self.set_hook(hook_name,getattr(hooks,hook_name), 100)
             #print "bound hook",hook_name
 
         # Flag to mark unconditional exit
         self.exit_now = False
 
         self.usage_min =  """\
         An enhanced console for Python.
         Some of its features are:
         - Readline support if the readline library is present.
         - Tab completion in the local namespace.
         - Logging of input, see command-line options.
         - System shell escape via ! , eg !ls.
         - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
         - Keeps track of locally defined variables via %who, %whos.
         - Show object information with a ? eg ?x or x? (use ?? for more info).
         """
         if usage: self.usage = usage
         else: self.usage = self.usage_min
 
         # Storage
         self.rc = rc   # This will hold all configuration information
         self.pager = 'less'
         # temporary files used for various purposes.  Deleted at exit.
         self.tempfiles = []
 
         # Keep track of readline usage (later set by init_readline)
         self.has_readline = False
 
         # template for logfile headers.  It gets resolved at runtime by the
         # logstart method.
         self.loghead_tpl = \
 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
 #log# opts = %s
 #log# args = %s
 #log# It is safe to make manual edits below here.
 #log#-----------------------------------------------------------------------
 """
         # for pushd/popd management
         try:
             self.home_dir = get_home_dir()
         except HomeDirError,msg:
             fatal(msg)
 
         self.dir_stack = []
 
         # Functions to call the underlying shell.
 
         # The first is similar to os.system, but it doesn't return a value,
         # and it allows interpolation of variables in the user's namespace.
         self.system = lambda cmd: \
                       self.hooks.shell_hook(self.var_expand(cmd,depth=2))
 
         # These are for getoutput and getoutputerror:
         self.getoutput = lambda cmd: \
                          getoutput(self.var_expand(cmd,depth=2),
                                    header=self.rc.system_header,
                                    verbose=self.rc.system_verbose)
 
         self.getoutputerror = lambda cmd: \
                               getoutputerror(self.var_expand(cmd,depth=2),
                                              header=self.rc.system_header,
                                              verbose=self.rc.system_verbose)
  
 
         # keep track of where we started running (mainly for crash post-mortem)
         self.starting_dir = os.getcwd()
 
         # Various switches which can be set
         self.CACHELENGTH = 5000  # this is cheap, it's just text
         self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
         self.banner2 = banner2
 
         # TraceBack handlers:
 
         # Syntax error handler.
         self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
         
         # The interactive one is initialized with an offset, meaning we always
         # want to remove the topmost item in the traceback, which is our own
         # internal code. Valid modes: ['Plain','Context','Verbose']
         self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
                                                      color_scheme='NoColor',
                                                      tb_offset = 1)
 
         # IPython itself shouldn't crash. This will produce a detailed
         # post-mortem if it does.  But we only install the crash handler for
         # non-threaded shells, the threaded ones use a normal verbose reporter
         # and lose the crash handler.  This is because exceptions in the main
         # thread (such as in GUI code) propagate directly to sys.excepthook,
         # and there's no point in printing crash dumps for every user exception.
         if self.isthreaded:
             ipCrashHandler = ultraTB.FormattedTB()
         else:
             from IPython import CrashHandler
             ipCrashHandler = CrashHandler.IPythonCrashHandler(self)
         self.set_crash_handler(ipCrashHandler)
 
         # and add any custom exception handlers the user may have specified
         self.set_custom_exc(*custom_exceptions)
 
         # indentation management
         self.autoindent = False
         self.indent_current_nsp = 0
 
         # Make some aliases automatically
         # Prepare list of shell aliases to auto-define
         if os.name == 'posix':
             auto_alias = ('mkdir mkdir', 'rmdir rmdir',
                           'mv mv -i','rm rm -i','cp cp -i',
                           'cat cat','less less','clear clear',
                           # a better ls
                           'ls ls -F',
                           # long ls
                           'll ls -lF')
             # Extra ls aliases with color, which need special treatment on BSD
             # variants
             ls_extra = ( # color ls
                          'lc ls -F -o --color',
                          # ls normal files only
                          'lf ls -F -o --color %l | grep ^-',
                          # ls symbolic links
                          'lk ls -F -o --color %l | grep ^l',
                          # directories or links to directories,
                          'ldir ls -F -o --color %l | grep /$',
                          # things which are executable
                          'lx ls -F -o --color %l | grep ^-..x',
                          )
             # The BSDs don't ship GNU ls, so they don't understand the
             # --color switch out of the box
             if 'bsd' in sys.platform:
                 ls_extra = ( # ls normal files only
                              'lf ls -lF | grep ^-',
                              # ls symbolic links
                              'lk ls -lF | grep ^l',
                              # directories or links to directories,
                              'ldir ls -lF | grep /$',
                              # things which are executable
                              'lx ls -lF | grep ^-..x',
                              )
             auto_alias = auto_alias + ls_extra
         elif os.name in ['nt','dos']:
             auto_alias = ('ls dir /on',
                           'ddir dir /ad /on', 'ldir dir /ad /on',
                           'mkdir mkdir','rmdir rmdir','echo echo',
                           'ren ren','cls cls','copy copy')
         else:
             auto_alias = ()
         self.auto_alias = [s.split(None,1) for s in auto_alias]
 
         
         # Produce a public API instance
         self.api = IPython.ipapi.IPApi(self)
 
         # Call the actual (public) initializer
         self.init_auto_alias()
 
         # track which builtins we add, so we can clean up later
         self.builtins_added = {}
         # This method will add the necessary builtins for operation, but
         # tracking what it did via the builtins_added dict.
         
         #TODO: remove this, redundant
         self.add_builtins()
 
         
         
 
     # end __init__
 
     def var_expand(self,cmd,depth=0):
         """Expand python variables in a string.
 
         The depth argument indicates how many frames above the caller should
         be walked to look for the local namespace where to expand variables.
 
         The global namespace for expansion is always the user's interactive
         namespace.
         """
 
         return str(ItplNS(cmd,
                           self.user_ns,  # globals
                           # Skip our own frame in searching for locals:
                           sys._getframe(depth+1).f_locals # locals
                           ))
 
     def pre_config_initialization(self):
         """Pre-configuration init method
 
         This is called before the configuration files are processed to
         prepare the services the config files might need.
         
         self.rc already has reasonable default values at this point.
         """
         rc = self.rc
         try:
             self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")            
         except exceptions.UnicodeDecodeError:
             print "Your ipythondir can't be decoded to unicode!"
             print "Please set HOME environment variable to something that"
             print r"only has ASCII characters, e.g. c:\home"
             print "Now it is",rc.ipythondir
             sys.exit()
         self.shadowhist = IPython.history.ShadowHist(self.db)            
             
     
     def post_config_initialization(self):
         """Post configuration init method
 
         This is called after the configuration files have been processed to
         'finalize' the initialization."""
 
         rc = self.rc
 
         # Object inspector
         self.inspector = OInspect.Inspector(OInspect.InspectColors,
                                             PyColorize.ANSICodeColors,
                                             'NoColor',
                                             rc.object_info_string_level)
         
         self.rl_next_input = None
         self.rl_do_indent = False
         # Load readline proper
         if rc.readline:
             self.init_readline()
 
         
         # local shortcut, this is used a LOT
         self.log = self.logger.log
 
         # Initialize cache, set in/out prompts and printing system
         self.outputcache = CachedOutput(self,
                                         rc.cache_size,
                                         rc.pprint,
                                         input_sep = rc.separate_in,
                                         output_sep = rc.separate_out,
                                         output_sep2 = rc.separate_out2,
                                         ps1 = rc.prompt_in1,
                                         ps2 = rc.prompt_in2,
                                         ps_out = rc.prompt_out,
                                         pad_left = rc.prompts_pad_left)
 
         # user may have over-ridden the default print hook:
         try:
             self.outputcache.__class__.display = self.hooks.display
         except AttributeError:
             pass
 
         # I don't like assigning globally to sys, because it means when
         # embedding instances, each embedded instance overrides the previous
         # choice. But sys.displayhook seems to be called internally by exec,
         # so I don't see a way around it.  We first save the original and then
         # overwrite it.
         self.sys_displayhook = sys.displayhook
         sys.displayhook = self.outputcache
 
         # Do a proper resetting of doctest, including the necessary displayhook
         # monkeypatching
         try:
             doctest_reload()
         except ImportError:
             warn("doctest module does not exist.")
         
         # Set user colors (don't do it in the constructor above so that it
         # doesn't crash if colors option is invalid)
         self.magic_colors(rc.colors)
 
         # Set calling of pdb on exceptions
         self.call_pdb = rc.pdb
 
         # Load user aliases
         for alias in rc.alias:
             self.magic_alias(alias)
         
         self.hooks.late_startup_hook()
         
         for cmd in self.rc.autoexec:
             #print "autoexec>",cmd #dbg
             self.api.runlines(cmd)
             
         batchrun = False
         for batchfile in [path(arg) for arg in self.rc.args 
             if arg.lower().endswith('.ipy')]:
             if not batchfile.isfile():
                 print "No such batch file:", batchfile
                 continue
             self.api.runlines(batchfile.text())
             batchrun = True
         # without -i option, exit after running the batch file
         if batchrun and not self.rc.interact:
             self.ask_exit()            
 
     def add_builtins(self):
         """Store ipython references into the builtin namespace.
 
         Some parts of ipython operate via builtins injected here, which hold a
         reference to IPython itself."""
 
         # TODO: deprecate all of these, they are unsafe
         builtins_new  = dict(__IPYTHON__ = self,
              ip_set_hook = self.set_hook, 
              jobs = self.jobs,
              ipmagic = wrap_deprecated(self.ipmagic,'_ip.magic()'),  
              ipalias = wrap_deprecated(self.ipalias),  
              ipsystem = wrap_deprecated(self.ipsystem,'_ip.system()'),
              #_ip = self.api
              )
         for biname,bival in builtins_new.items():
             try:
                 # store the orignal value so we can restore it
                 self.builtins_added[biname] =  __builtin__.__dict__[biname]
             except KeyError:
                 # or mark that it wasn't defined, and we'll just delete it at
                 # cleanup
                 self.builtins_added[biname] = Undefined
             __builtin__.__dict__[biname] = bival
             
         # Keep in the builtins a flag for when IPython is active.  We set it
         # with setdefault so that multiple nested IPythons don't clobber one
         # another.  Each will increase its value by one upon being activated,
         # which also gives us a way to determine the nesting level.
         __builtin__.__dict__.setdefault('__IPYTHON__active',0)
 
     def clean_builtins(self):
         """Remove any builtins which might have been added by add_builtins, or
         restore overwritten ones to their previous values."""
         for biname,bival in self.builtins_added.items():
             if bival is Undefined:
                 del __builtin__.__dict__[biname]
             else:
                 __builtin__.__dict__[biname] = bival
         self.builtins_added.clear()
     
     def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
         """set_hook(name,hook) -> sets an internal IPython hook.
 
         IPython exposes some of its internal API as user-modifiable hooks.  By
         adding your function to one of these hooks, you can modify IPython's 
         behavior to call at runtime your own routines."""
 
         # At some point in the future, this should validate the hook before it
         # accepts it.  Probably at least check that the hook takes the number
         # of args it's supposed to.
         
         f = new.instancemethod(hook,self,self.__class__)
 
         # check if the hook is for strdispatcher first
         if str_key is not None:
             sdp = self.strdispatchers.get(name, StrDispatch())
             sdp.add_s(str_key, f, priority )
             self.strdispatchers[name] = sdp
             return
         if re_key is not None:
             sdp = self.strdispatchers.get(name, StrDispatch())
             sdp.add_re(re.compile(re_key), f, priority )
             self.strdispatchers[name] = sdp
             return
             
         dp = getattr(self.hooks, name, None)
         if name not in IPython.hooks.__all__:
             print "Warning! Hook '%s' is not one of %s" % (name, IPython.hooks.__all__ )
         if not dp:
             dp = IPython.hooks.CommandChainDispatcher()
         
         try:
             dp.add(f,priority)
         except AttributeError:
             # it was not commandchain, plain old func - replace
             dp = f
 
         setattr(self.hooks,name, dp)
         
         
         #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
 
     def set_crash_handler(self,crashHandler):
         """Set the IPython crash handler.
 
         This must be a callable with a signature suitable for use as
         sys.excepthook."""
 
         # Install the given crash handler as the Python exception hook
         sys.excepthook = crashHandler
         
         # The instance will store a pointer to this, so that runtime code
         # (such as magics) can access it.  This is because during the
         # read-eval loop, it gets temporarily overwritten (to deal with GUI
         # frameworks).
         self.sys_excepthook = sys.excepthook
 
 
     def set_custom_exc(self,exc_tuple,handler):
         """set_custom_exc(exc_tuple,handler)
 
         Set a custom exception handler, which will be called if any of the
         exceptions in exc_tuple occur in the mainloop (specifically, in the
         runcode() method.
 
         Inputs:
 
           - exc_tuple: a *tuple* of valid exceptions to call the defined
           handler for.  It is very important that you use a tuple, and NOT A
           LIST here, because of the way Python's except statement works.  If
           you only want to trap a single exception, use a singleton tuple:
 
             exc_tuple == (MyCustomException,)
 
           - handler: this must be defined as a function with the following
           basic interface: def my_handler(self,etype,value,tb).
 
           This will be made into an instance method (via new.instancemethod)
           of IPython itself, and it will be called if any of the exceptions
           listed in the exc_tuple are caught.  If the handler is None, an
           internal basic one is used, which just prints basic info.
 
         WARNING: by putting in your own exception handler into IPython's main
         execution loop, you run a very good chance of nasty crashes.  This
         facility should only be used if you really know what you are doing."""
 
         assert type(exc_tuple)==type(()) , \
                "The custom exceptions must be given AS A TUPLE."
 
         def dummy_handler(self,etype,value,tb):
             print '*** Simple custom exception handler ***'
             print 'Exception type :',etype
             print 'Exception value:',value
             print 'Traceback      :',tb
             print 'Source code    :','\n'.join(self.buffer)
 
         if handler is None: handler = dummy_handler
 
         self.CustomTB = new.instancemethod(handler,self,self.__class__)
         self.custom_exceptions = exc_tuple
 
     def set_custom_completer(self,completer,pos=0):
         """set_custom_completer(completer,pos=0)
 
         Adds a new custom completer function.
 
         The position argument (defaults to 0) is the index in the completers
         list where you want the completer to be inserted."""
 
         newcomp = new.instancemethod(completer,self.Completer,
                                      self.Completer.__class__)
         self.Completer.matchers.insert(pos,newcomp)
 
     def set_completer(self):
         """reset readline's completer to be our own."""
         self.readline.set_completer(self.Completer.complete)
         
     def _get_call_pdb(self):
         return self._call_pdb
 
     def _set_call_pdb(self,val):
 
         if val not in (0,1,False,True):
             raise ValueError,'new call_pdb value must be boolean'
 
         # store value in instance
         self._call_pdb = val
 
         # notify the actual exception handlers
         self.InteractiveTB.call_pdb = val
         if self.isthreaded:
             try:
                 self.sys_excepthook.call_pdb = val
             except:
                 warn('Failed to activate pdb for threaded exception handler')
 
     call_pdb = property(_get_call_pdb,_set_call_pdb,None,
                         'Control auto-activation of pdb at exceptions')
  
 
     # These special functions get installed in the builtin namespace, to
     # provide programmatic (pure python) access to magics, aliases and system
     # calls.  This is important for logging, user scripting, and more.
 
     # We are basically exposing, via normal python functions, the three
     # mechanisms in which ipython offers special call modes (magics for
     # internal control, aliases for direct system access via pre-selected
     # names, and !cmd for calling arbitrary system commands).
 
     def ipmagic(self,arg_s):
         """Call a magic function by name.
 
         Input: a string containing the name of the magic function to call and any
         additional arguments to be passed to the magic.
 
         ipmagic('name -opt foo bar') is equivalent to typing at the ipython
         prompt:
 
         In[1]: %name -opt foo bar
 
         To call a magic without arguments, simply use ipmagic('name').
 
         This provides a proper Python function to call IPython's magics in any
         valid Python code you can type at the interpreter, including loops and
         compound statements.  It is added by IPython to the Python builtin
         namespace upon initialization."""
 
         args = arg_s.split(' ',1)
         magic_name = args[0]
         magic_name = magic_name.lstrip(self.ESC_MAGIC)
 
         try:
             magic_args = args[1]
         except IndexError:
             magic_args = ''
         fn = getattr(self,'magic_'+magic_name,None)
         if fn is None:
             error("Magic function `%s` not found." % magic_name)
         else:
             magic_args = self.var_expand(magic_args,1)
             return fn(magic_args)
 
     def ipalias(self,arg_s):
         """Call an alias by name.
 
         Input: a string containing the name of the alias to call and any
         additional arguments to be passed to the magic.
 
         ipalias('name -opt foo bar') is equivalent to typing at the ipython
         prompt:
 
         In[1]: name -opt foo bar
 
         To call an alias without arguments, simply use ipalias('name').
 
         This provides a proper Python function to call IPython's aliases in any
         valid Python code you can type at the interpreter, including loops and
         compound statements.  It is added by IPython to the Python builtin
         namespace upon initialization."""
 
         args = arg_s.split(' ',1)
         alias_name = args[0]
         try:
             alias_args = args[1]
         except IndexError:
             alias_args = ''
         if alias_name in self.alias_table:
             self.call_alias(alias_name,alias_args)
         else:
             error("Alias `%s` not found." % alias_name)
 
     def ipsystem(self,arg_s):
         """Make a system call, using IPython."""
 
         self.system(arg_s)
 
     def complete(self,text):
         """Return a sorted list of all possible completions on text.
 
         Inputs:
 
           - text: a string of text to be completed on.
 
         This is a wrapper around the completion mechanism, similar to what
         readline does at the command line when the TAB key is hit.  By
         exposing it as a method, it can be used by other non-readline
         environments (such as GUIs) for text completion.
 
         Simple usage example:
 
         In [7]: x = 'hello'
 
         In [8]: x
         Out[8]: 'hello'
 
         In [9]: print x
         hello
 
         In [10]: _ip.IP.complete('x.l')
         Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
         """
         
         complete = self.Completer.complete
         state = 0
         # use a dict so we get unique keys, since ipyhton's multiple
         # completers can return duplicates.  When we make 2.4 a requirement,
         # start using sets instead, which are faster.
         comps = {}
         while True:
             newcomp = complete(text,state,line_buffer=text)
             if newcomp is None:
                 break
             comps[newcomp] = 1
             state += 1
         outcomps = comps.keys()
         outcomps.sort()
         #print "T:",text,"OC:",outcomps  # dbg
         #print "vars:",self.user_ns.keys()
         return outcomps
         
     def set_completer_frame(self, frame=None):
         if frame:
             self.Completer.namespace = frame.f_locals
             self.Completer.global_namespace = frame.f_globals
         else:
             self.Completer.namespace = self.user_ns
             self.Completer.global_namespace = self.user_global_ns
 
     def init_auto_alias(self):
         """Define some aliases automatically.
 
         These are ALL parameter-less aliases"""
 
         for alias,cmd in self.auto_alias:
             self.getapi().defalias(alias,cmd)
             
 
     def alias_table_validate(self,verbose=0):
         """Update information about the alias table.
 
         In particular, make sure no Python keywords/builtins are in it."""
 
         no_alias = self.no_alias
         for k in self.alias_table.keys():
             if k in no_alias:
                 del self.alias_table[k]
                 if verbose:
                     print ("Deleting alias <%s>, it's a Python "
                            "keyword or builtin." % k)
     
     def set_autoindent(self,value=None):
         """Set the autoindent flag, checking for readline support.
 
         If called with no arguments, it acts as a toggle."""
 
         if not self.has_readline:
             if os.name == 'posix':
                 warn("The auto-indent feature requires the readline library")
             self.autoindent = 0
             return
         if value is None:
             self.autoindent = not self.autoindent
         else:
             self.autoindent = value
 
     def rc_set_toggle(self,rc_field,value=None):
         """Set or toggle a field in IPython's rc config. structure.
 
         If called with no arguments, it acts as a toggle.
 
         If called with a non-existent field, the resulting AttributeError
         exception will propagate out."""
 
         rc_val = getattr(self.rc,rc_field)
         if value is None:
             value = not rc_val
         setattr(self.rc,rc_field,value)
 
     def user_setup(self,ipythondir,rc_suffix,mode='install'):
         """Install the user configuration directory.
 
         Can be called when running for the first time or to upgrade the user's
         .ipython/ directory with the mode parameter. Valid modes are 'install'
         and 'upgrade'."""
 
         def wait():
             try:
                 raw_input("Please press <RETURN> to start IPython.")
             except EOFError:
                 print >> Term.cout
             print '*'*70
 
         cwd = os.getcwd()  # remember where we started
         glb = glob.glob
         print '*'*70
         if mode == 'install':
             print \
 """Welcome to IPython. I will try to create a personal configuration directory
 where you can customize many aspects of IPython's functionality in:\n"""
         else:
             print 'I am going to upgrade your configuration in:'
 
         print ipythondir
 
         rcdirend = os.path.join('IPython','UserConfig')
         cfg = lambda d: os.path.join(d,rcdirend)
         try:
             rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
             print "Initializing from configuration",rcdir
         except IndexError:
             warning = """
 Installation error. IPython's directory was not found.
 
 Check the following:
 
 The ipython/IPython directory should be in a directory belonging to your
 PYTHONPATH environment variable (that is, it should be in a directory
 belonging to sys.path). You can copy it explicitly there or just link to it.
 
 IPython will create a minimal default configuration for you.
 
 """
             warn(warning)
             wait()
             
             if sys.platform =='win32':
                 inif = 'ipythonrc.ini'
             else:
                 inif = 'ipythonrc'
             minimal_setup = {'ipy_user_conf.py' : 'import ipy_defaults', inif : '# intentionally left blank' }    
             os.makedirs(ipythondir, mode = 0777)
             for f, cont in minimal_setup.items():
                 open(ipythondir + '/' + f,'w').write(cont)
                              
             return
 
         if mode == 'install':
             try:
                 shutil.copytree(rcdir,ipythondir)
                 os.chdir(ipythondir)
                 rc_files = glb("ipythonrc*")
                 for rc_file in rc_files:
                     os.rename(rc_file,rc_file+rc_suffix)
             except:
                 warning = """
 
 There was a problem with the installation:
 %s
 Try to correct it or contact the developers if you think it's a bug.
 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
                 warn(warning)
                 wait()
                 return
 
         elif mode == 'upgrade':
             try:
                 os.chdir(ipythondir)
             except:
                 print """
 Can not upgrade: changing to directory %s failed. Details:
 %s
 """ % (ipythondir,sys.exc_info()[1])
                 wait()
                 return
             else:
                 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
                 for new_full_path in sources:
                     new_filename = os.path.basename(new_full_path)
                     if new_filename.startswith('ipythonrc'):
                         new_filename = new_filename + rc_suffix
                     # The config directory should only contain files, skip any
                     # directories which may be there (like CVS)
                     if os.path.isdir(new_full_path):
                         continue
                     if os.path.exists(new_filename):
                         old_file = new_filename+'.old'
                         if os.path.exists(old_file):
                             os.remove(old_file)
                         os.rename(new_filename,old_file)
                     shutil.copy(new_full_path,new_filename)
         else:
             raise ValueError,'unrecognized mode for install:',`mode`
 
         # Fix line-endings to those native to each platform in the config
         # directory.
         try:
             os.chdir(ipythondir)
         except:
             print """
 Problem: changing to directory %s failed.
 Details:
 %s
 
 Some configuration files may have incorrect line endings.  This should not
 cause any problems during execution.  """ % (ipythondir,sys.exc_info()[1])
             wait()
         else:
             for fname in glb('ipythonrc*'):
                 try:
                     native_line_ends(fname,backup=0)
                 except IOError:
                     pass
 
         if mode == 'install':
             print """
 Successful installation!
 
 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
 IPython manual (there are both HTML and PDF versions supplied with the
 distribution) to make sure that your system environment is properly configured
 to take advantage of IPython's features.
 
 Important note: the configuration system has changed! The old system is
 still in place, but its setting may be partly overridden by the settings in 
 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file 
 if some of the new settings bother you. 
 
 """
         else:
             print """
 Successful upgrade!
 
 All files in your directory:
 %(ipythondir)s
 which would have been overwritten by the upgrade were backed up with a .old
 extension.  If you had made particular customizations in those files you may
 want to merge them back into the new files.""" % locals()
         wait()
         os.chdir(cwd)
         # end user_setup()
 
     def atexit_operations(self):
         """This will be executed at the time of exit.
 
         Saving of persistent data should be performed here. """
 
         #print '*** IPython exit cleanup ***' # dbg
         # input history
         self.savehist()
 
         # Cleanup all tempfiles left around
         for tfile in self.tempfiles:
             try:
                 os.unlink(tfile)
             except OSError:
                 pass
 
         self.hooks.shutdown_hook()
         
     def savehist(self):
         """Save input history to a file (via readline library)."""
 
         if not self.has_readline:
             return
         
         try:
             self.readline.write_history_file(self.histfile)
         except:
             print 'Unable to save IPython command history to file: ' + \
                   `self.histfile`
 
     def reloadhist(self):
         """Reload the input history from disk file."""
 
         if self.has_readline:
             try:
                 self.readline.clear_history()
                 self.readline.read_history_file(self.shell.histfile)
             except AttributeError:
                 pass
             
 
     def history_saving_wrapper(self, func):
         """ Wrap func for readline history saving
         
         Convert func into callable that saves & restores
         history around the call """
         
         if not self.has_readline:
             return func
         
         def wrapper():
             self.savehist()
             try:
                 func()
             finally:
                 readline.read_history_file(self.histfile)
         return wrapper
                 
             
     def pre_readline(self):
         """readline hook to be used at the start of each line.
 
         Currently it handles auto-indent only."""
 
         #debugx('self.indent_current_nsp','pre_readline:')
 
         if self.rl_do_indent:
             self.readline.insert_text(self.indent_current_str())
         if self.rl_next_input is not None:
             self.readline.insert_text(self.rl_next_input)
             self.rl_next_input = None
 
     def init_readline(self):
         """Command history completion/saving/reloading."""
 
 
         import IPython.rlineimpl as readline
                   
         if not readline.have_readline:
             self.has_readline = 0
             self.readline = None
             # no point in bugging windows users with this every time:
             warn('Readline services not available on this platform.')
         else:
             sys.modules['readline'] = readline
             import atexit
             from IPython.completer import IPCompleter
             self.Completer = IPCompleter(self,
                                             self.user_ns,
                                             self.user_global_ns,
                                             self.rc.readline_omit__names,
                                             self.alias_table)
             sdisp = self.strdispatchers.get('complete_command', StrDispatch())
             self.strdispatchers['complete_command'] = sdisp
             self.Completer.custom_completers = sdisp
             # Platform-specific configuration
             if os.name == 'nt':
                 self.readline_startup_hook = readline.set_pre_input_hook
             else:
                 self.readline_startup_hook = readline.set_startup_hook
 
             # Load user's initrc file (readline config)
             # Or if libedit is used, load editrc.
             inputrc_name = os.environ.get('INPUTRC')
             if inputrc_name is None:
                 home_dir = get_home_dir()
                 if home_dir is not None:
                     inputrc_name = '.inputrc'
                     if readline.uses_libedit:
                         inputrc_name = '.editrc'
                     inputrc_name = os.path.join(home_dir, inputrc_name)
             if os.path.isfile(inputrc_name):
                 try:
                     readline.read_init_file(inputrc_name)
                 except:
                     warn('Problems reading readline initialization file <%s>'
                          % inputrc_name)
             
             self.has_readline = 1
             self.readline = readline
             # save this in sys so embedded copies can restore it properly
             sys.ipcompleter = self.Completer.complete
             self.set_completer()
 
             # Configure readline according to user's prefs
             # This is only done if GNU readline is being used.  If libedit
             # is being used (as on Leopard) the readline config is
             # not run as the syntax for libedit is different.
             if not readline.uses_libedit:
                 for rlcommand in self.rc.readline_parse_and_bind:
                     readline.parse_and_bind(rlcommand)
 
             # remove some chars from the delimiters list
             delims = readline.get_completer_delims()
             delims = delims.translate(string._idmap,
                                       self.rc.readline_remove_delims)
             readline.set_completer_delims(delims)
             # otherwise we end up with a monster history after a while:
             readline.set_history_length(1000)
             try:
                 #print '*** Reading readline history'  # dbg
                 readline.read_history_file(self.histfile)
             except IOError:
                 pass  # It doesn't exist yet.
 
             atexit.register(self.atexit_operations)
             del atexit
 
         # Configure auto-indent for all platforms
         self.set_autoindent(self.rc.autoindent)
 
     def ask_yes_no(self,prompt,default=True):
         if self.rc.quiet:
             return True
         return ask_yes_no(prompt,default)
     
     def _should_recompile(self,e):
         """Utility routine for edit_syntax_error"""
 
         if e.filename in ('<ipython console>','<input>','<string>',
                           '<console>','<BackgroundJob compilation>',
                           None):
                               
             return False
         try:
             if (self.rc.autoedit_syntax and 
                 not self.ask_yes_no('Return to editor to correct syntax error? '
                               '[Y/n] ','y')):
                 return False
         except EOFError:
             return False
 
         def int0(x):
             try:
                 return int(x)
             except TypeError:
                 return 0
         # always pass integer line and offset values to editor hook
-        self.hooks.fix_error_editor(e.filename,
-            int0(e.lineno),int0(e.offset),e.msg)
+        try:
+            self.hooks.fix_error_editor(e.filename,
+                int0(e.lineno),int0(e.offset),e.msg)
+        except IPython.ipapi.TryNext:
+            warn('Could not open editor')
+            return False
         return True
         
     def edit_syntax_error(self):
         """The bottom half of the syntax error handler called in the main loop.
 
         Loop until syntax error is fixed or user cancels.
         """
 
         while self.SyntaxTB.last_syntax_error:
             # copy and clear last_syntax_error
             err = self.SyntaxTB.clear_err_state()
             if not self._should_recompile(err):
                 return
             try:
                 # may set last_syntax_error again if a SyntaxError is raised
                 self.safe_execfile(err.filename,self.user_ns)
             except:
                 self.showtraceback()
             else:
                 try:
                     f = file(err.filename)
                     try:
                         sys.displayhook(f.read())
                     finally:
                         f.close()
                 except:
                     self.showtraceback()
 
     def showsyntaxerror(self, filename=None):
         """Display the syntax error that just occurred.
 
         This doesn't display a stack trace because there isn't one.
 
         If a filename is given, it is stuffed in the exception instead
         of what was there before (because Python's parser always uses
         "<string>" when reading from a string).
         """
         etype, value, last_traceback = sys.exc_info()
 
         # See note about these variables in showtraceback() below
         sys.last_type = etype
         sys.last_value = value
         sys.last_traceback = last_traceback
         
         if filename and etype is SyntaxError:
             # Work hard to stuff the correct filename in the exception
             try:
                 msg, (dummy_filename, lineno, offset, line) = value
             except:
                 # Not the format we expect; leave it alone
                 pass
             else:
                 # Stuff in the right filename
                 try:
                     # Assume SyntaxError is a class exception
                     value = SyntaxError(msg, (filename, lineno, offset, line))
                 except:
                     # If that failed, assume SyntaxError is a string
                     value = msg, (filename, lineno, offset, line)
         self.SyntaxTB(etype,value,[])
 
     def debugger(self,force=False):
         """Call the pydb/pdb debugger.
 
         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 not (force or self.call_pdb):
             return
 
         if not hasattr(sys,'last_traceback'):
             error('No traceback has been produced, nothing to debug.')
             return
 
         # use pydb if available
         if Debugger.has_pydb:
             from pydb import pm
         else:
             # fallback to our internal debugger
             pm = lambda : self.InteractiveTB.debugger(force=True)
         self.history_saving_wrapper(pm)()
 
     def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
         """Display the exception that just occurred.
 
         If nothing is known about the exception, this is the method which
         should be used throughout the code for presenting user tracebacks,
         rather than directly invoking the InteractiveTB object.
 
         A specific showsyntaxerror() also exists, but this method can take
         care of calling it if needed, so unless you are explicitly catching a
         SyntaxError exception, don't try to analyze the stack manually and
         simply call this method."""
 
         
         # Though this won't be called by syntax errors in the input line,
         # there may be SyntaxError cases whith imported code.
         
         try:
             if exc_tuple is None:
                 etype, value, tb = sys.exc_info()
             else:
                 etype, value, tb = exc_tuple
     
             if etype is SyntaxError:
                 self.showsyntaxerror(filename)
             elif etype is IPython.ipapi.UsageError:
                 print "UsageError:", value
             else:
                 # WARNING: these variables are somewhat deprecated and not
                 # necessarily safe to use in a threaded environment, but tools
                 # like pdb depend on their existence, so let's set them.  If we
                 # find problems in the field, we'll need to revisit their use.
                 sys.last_type = etype
                 sys.last_value = value
                 sys.last_traceback = tb
     
                 if etype in self.custom_exceptions:
                     self.CustomTB(etype,value,tb)
                 else:
                     self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
                     if self.InteractiveTB.call_pdb and self.has_readline:
                         # pdb mucks up readline, fix it back
                         self.set_completer()
         except KeyboardInterrupt:
             self.write("\nKeyboardInterrupt\n")
             
         
 
     def mainloop(self,banner=None):
         """Creates the local namespace and starts the mainloop.
 
         If an optional banner argument is given, it will override the
         internally created default banner."""
 
         if self.rc.c:  # Emulate Python's -c option
             self.exec_init_cmd()
         if banner is None:
             if not self.rc.banner:
                 banner = ''
             # banner is string? Use it directly!
             elif isinstance(self.rc.banner,basestring):
                 banner = self.rc.banner
             else:                
                 banner = self.BANNER+self.banner2
 
+        # if you run stuff with -c <cmd>, raw hist is not updated
+        # ensure that it's in sync
+        if len(self.input_hist) != len (self.input_hist_raw):
+            self.input_hist_raw = InputList(self.input_hist)
+
         while 1:
             try:
                 self.interact(banner)
                 #self.interact_with_readline()                
                 # XXX for testing of a readline-decoupled repl loop, call interact_with_readline above
 
                 break
             except KeyboardInterrupt:
                 # this should not be necessary, but KeyboardInterrupt
                 # handling seems rather unpredictable...
                 self.write("\nKeyboardInterrupt in interact()\n")
 
     def exec_init_cmd(self):
         """Execute a command given at the command line.
 
         This emulates Python's -c option."""
 
         #sys.argv = ['-c']
         self.push(self.prefilter(self.rc.c, False))
         if not self.rc.interact:
             self.ask_exit()
 
     def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
         """Embeds IPython into a running python program.
 
         Input:
 
           - header: An optional header message can be specified.
 
           - local_ns, global_ns: working namespaces. If given as None, the
           IPython-initialized one is updated with __main__.__dict__, so that
           program variables become visible but user-specific configuration
           remains possible.
 
           - stack_depth: specifies how many levels in the stack to go to
           looking for namespaces (when local_ns and global_ns are None).  This
           allows an intermediate caller to make sure that this function gets
           the namespace from the intended level in the stack.  By default (0)
           it will get its locals and globals from the immediate caller.
 
         Warning: it's possible to use this in a program which is being run by
         IPython itself (via %run), but some funny things will happen (a few
         globals get overwritten). In the future this will be cleaned up, as
         there is no fundamental reason why it can't work perfectly."""
 
         # Get locals and globals from caller
         if local_ns is None or global_ns is None:
             call_frame = sys._getframe(stack_depth).f_back
 
             if local_ns is None:
                 local_ns = call_frame.f_locals
             if global_ns is None:
                 global_ns = call_frame.f_globals
 
         # Update namespaces and fire up interpreter
 
         # The global one is easy, we can just throw it in
         self.user_global_ns = global_ns
 
         # but the user/local one is tricky: ipython needs it to store internal
         # data, but we also need the locals.  We'll copy locals in the user
         # one, but will track what got copied so we can delete them at exit.
         # This is so that a later embedded call doesn't see locals from a
         # previous call (which most likely existed in a separate scope).
         local_varnames = local_ns.keys()
         self.user_ns.update(local_ns)
         #self.user_ns['local_ns'] = local_ns  # dbg
 
         # Patch for global embedding to make sure that things don't overwrite
         # user globals accidentally. Thanks to Richard <[e-mail]>
         # FIXME. Test this a bit more carefully (the if.. is new)
         if local_ns is None and global_ns is None:
             self.user_global_ns.update(__main__.__dict__)
 
         # make sure the tab-completer has the correct frame information, so it
         # actually completes using the frame's locals/globals
         self.set_completer_frame()
 
         # before activating the interactive mode, we need to make sure that
         # all names in the builtin namespace needed by ipython point to
         # ourselves, and not to other instances.
         self.add_builtins()
 
         self.interact(header)
         
         # now, purge out the user namespace from anything we might have added
         # from the caller's local namespace
         delvar = self.user_ns.pop
         for var in local_varnames:
             delvar(var,None)
         # and clean builtins we may have overridden
         self.clean_builtins()
 
     def interact_prompt(self):
         """ Print the prompt (in read-eval-print loop) 
 
         Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not 
         used in standard IPython flow.
         """
         if self.more:
             try:
                 prompt = self.hooks.generate_prompt(True)
             except:
                 self.showtraceback()
             if self.autoindent:
                 self.rl_do_indent = True
 
         else:
             try:
                 prompt = self.hooks.generate_prompt(False)
             except:
                 self.showtraceback()
         self.write(prompt)
 
     def interact_handle_input(self,line):
         """ Handle the input line (in read-eval-print loop)
         
         Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not 
         used in standard IPython flow.        
         """
         if line.lstrip() == line:
             self.shadowhist.add(line.strip())
         lineout = self.prefilter(line,self.more)
 
         if line.strip():
             if self.more:
                 self.input_hist_raw[-1] += '%s\n' % line
             else:
                 self.input_hist_raw.append('%s\n' % line)                
 
         
         self.more = self.push(lineout)
         if (self.SyntaxTB.last_syntax_error and
             self.rc.autoedit_syntax):
             self.edit_syntax_error()
 
     def interact_with_readline(self):
         """ Demo of using interact_handle_input, interact_prompt
         
         This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
         it should work like this.
         """ 
         self.readline_startup_hook(self.pre_readline)
         while not self.exit_now:
             self.interact_prompt()
             if self.more:
                 self.rl_do_indent = True
             else:
                 self.rl_do_indent = False
             line = raw_input_original().decode(self.stdin_encoding)
             self.interact_handle_input(line)
 
         
     def interact(self, banner=None):
         """Closely emulate the interactive Python console.
 
         The optional banner argument specify the banner to print
         before the first interaction; by default it prints a banner
         similar to the one printed by the real Python interpreter,
         followed by the current class name in parentheses (so as not
         to confuse this with the real interpreter -- since it's so
         close!).
 
         """
         
         if self.exit_now:
             # batch run -> do not interact
             return
         cprt = 'Type "copyright", "credits" or "license" for more information.'
         if banner is None:
             self.write("Python %s on %s\n%s\n(%s)\n" %
                        (sys.version, sys.platform, cprt,
                         self.__class__.__name__))
         else:
             self.write(banner)
 
         more = 0
         
         # Mark activity in the builtins
         __builtin__.__dict__['__IPYTHON__active'] += 1
         
         if self.has_readline:
             self.readline_startup_hook(self.pre_readline)
         # exit_now is set by a call to %Exit or %Quit, through the
         # ask_exit callback.
         
         while not self.exit_now:
             self.hooks.pre_prompt_hook()
             if more:
                 try:
                     prompt = self.hooks.generate_prompt(True)
                 except:
                     self.showtraceback()
                 if self.autoindent:
                     self.rl_do_indent = True
                     
             else:
                 try:
                     prompt = self.hooks.generate_prompt(False)
                 except:
                     self.showtraceback()
             try:
                 line = self.raw_input(prompt,more)
                 if self.exit_now:
                     # quick exit on sys.std[in|out] close
                     break
                 if self.autoindent:
                     self.rl_do_indent = False
                     
             except KeyboardInterrupt:
                 #double-guard against keyboardinterrupts during kbdint handling
                 try:
                     self.write('\nKeyboardInterrupt\n')
                     self.resetbuffer()
                     # keep cache in sync with the prompt counter:
                     self.outputcache.prompt_count -= 1
     
                     if self.autoindent:
                         self.indent_current_nsp = 0
                     more = 0
                 except KeyboardInterrupt:
                     pass
             except EOFError:
                 if self.autoindent:
                     self.rl_do_indent = False
                     self.readline_startup_hook(None)
                 self.write('\n')
                 self.exit()
             except bdb.BdbQuit:
                 warn('The Python debugger has exited with a BdbQuit exception.\n'
                      'Because of how pdb handles the stack, it is impossible\n'
                      'for IPython to properly format this particular exception.\n'
                      'IPython will resume normal operation.')
             except:
                 # exceptions here are VERY RARE, but they can be triggered
                 # asynchronously by signal handlers, for example.
                 self.showtraceback()
             else:
                 more = self.push(line)
                 if (self.SyntaxTB.last_syntax_error and
                     self.rc.autoedit_syntax):
                     self.edit_syntax_error()
             
         # We are off again...
         __builtin__.__dict__['__IPYTHON__active'] -= 1
 
     def excepthook(self, etype, value, tb):
       """One more defense for GUI apps that call sys.excepthook.
 
       GUI frameworks like wxPython trap exceptions and call
       sys.excepthook themselves.  I guess this is a feature that
       enables them to keep running after exceptions that would
       otherwise kill their mainloop. This is a bother for IPython
       which excepts to catch all of the program exceptions with a try:
       except: statement.
 
       Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
       any app directly invokes sys.excepthook, it will look to the user like
       IPython crashed.  In order to work around this, we can disable the
       CrashHandler and replace it with this excepthook instead, which prints a
       regular traceback using our InteractiveTB.  In this fashion, apps which
       call sys.excepthook will generate a regular-looking exception from
       IPython, and the CrashHandler will only be triggered by real IPython
       crashes.
 
       This hook should be used sparingly, only in places which are not likely
       to be true IPython errors.
       """
       self.showtraceback((etype,value,tb),tb_offset=0)
 
     def expand_aliases(self,fn,rest):
         """ Expand multiple levels of aliases:
         
         if:
         
         alias foo bar /tmp
         alias baz foo
         
         then:
         
         baz huhhahhei -> bar /tmp huhhahhei
         
         """
         line = fn + " " + rest
         
         done = Set()
         while 1:
             pre,fn,rest = prefilter.splitUserInput(line,
                                                    prefilter.shell_line_split)
             if fn in self.alias_table:
                 if fn in done:
                     warn("Cyclic alias definition, repeated '%s'" % fn)
                     return ""
                 done.add(fn)
 
                 l2 = self.transform_alias(fn,rest)
                 # dir -> dir 
                 # print "alias",line, "->",l2  #dbg
                 if l2 == line:
                     break
                 # ls -> ls -F should not recurse forever
                 if l2.split(None,1)[0] == line.split(None,1)[0]:
                     line = l2
                     break
                 
                 line=l2
                 
                 
                 # print "al expand to",line #dbg
             else:
                 break
                 
         return line
 
     def transform_alias(self, alias,rest=''):
         """ Transform alias to system command string.
         """
         trg = self.alias_table[alias]
 
         nargs,cmd = trg
         # print trg #dbg
         if ' ' in cmd and os.path.isfile(cmd):
             cmd = '"%s"' % cmd
 
         # Expand the %l special to be the user's input line
         if cmd.find('%l') >= 0:
             cmd = cmd.replace('%l',rest)
             rest = ''
         if nargs==0:
             # Simple, argument-less aliases
             cmd = '%s %s' % (cmd,rest)
         else:
             # Handle aliases with positional arguments
             args = rest.split(None,nargs)
             if len(args)< nargs:
                 error('Alias <%s> requires %s arguments, %s given.' %
                       (alias,nargs,len(args)))
                 return None
             cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
         # Now call the macro, evaluating in the user's namespace
         #print 'new command: <%r>' % cmd  # dbg
         return cmd
         
     def call_alias(self,alias,rest=''):
         """Call an alias given its name and the rest of the line.
 
         This is only used to provide backwards compatibility for users of
         ipalias(), use of which is not recommended for anymore."""
 
         # Now call the macro, evaluating in the user's namespace
         cmd = self.transform_alias(alias, rest)
         try:
             self.system(cmd)
         except:
             self.showtraceback()
 
     def indent_current_str(self):
         """return the current level of indentation as a string"""
         return self.indent_current_nsp * ' '
 
     def autoindent_update(self,line):
         """Keep track of the indent level."""
 
         #debugx('line')
         #debugx('self.indent_current_nsp')
         if self.autoindent:
             if line:
                 inisp = num_ini_spaces(line)
                 if inisp < self.indent_current_nsp:
                     self.indent_current_nsp = inisp
 
                 if line[-1] == ':':
                     self.indent_current_nsp += 4
                 elif dedent_re.match(line):
                     self.indent_current_nsp -= 4
             else:
                 self.indent_current_nsp = 0
 
     def runlines(self,lines):
         """Run a string of one or more lines of source.
 
         This method is capable of running a string containing multiple source
         lines, as if they had been entered at the IPython prompt.  Since it
         exposes IPython's processing machinery, the given strings can contain
         magic calls (%magic), special shell access (!cmd), etc."""
 
         # We must start with a clean buffer, in case this is run from an
         # interactive IPython session (via a magic, for example).
         self.resetbuffer()
         lines = lines.split('\n')
         more = 0
     
         for line in lines:
             # skip blank lines so we don't mess up the prompt counter, but do
             # NOT skip even a blank line if we are in a code block (more is
             # true)
             
             
             if line or more:
                 # push to raw history, so hist line numbers stay in sync
                 self.input_hist_raw.append("# " + line + "\n")
                 more = self.push(self.prefilter(line,more))
                 # IPython's runsource returns None if there was an error
                 # compiling the code.  This allows us to stop processing right
                 # away, so the user gets the error message at the right place.
                 if more is None:
                     break
             else:
                 self.input_hist_raw.append("\n")
         # final newline in case the input didn't have it, so that the code
         # actually does get executed
         if more:
             self.push('\n')
 
     def runsource(self, source, filename='<input>', symbol='single'):
         """Compile and run some source in the interpreter.
 
         Arguments are as for compile_command().
 
         One several things can happen:
 
         1) The input is incorrect; compile_command() raised an
         exception (SyntaxError or OverflowError).  A syntax traceback
         will be printed by calling the showsyntaxerror() method.
 
         2) The input is incomplete, and more input is required;
         compile_command() returned None.  Nothing happens.
 
         3) The input is complete; compile_command() returned a code
         object.  The code is executed by calling self.runcode() (which
         also handles run-time exceptions, except for SystemExit).
 
         The return value is:
 
           - True in case 2
 
           - False in the other cases, unless an exception is raised, where
           None is returned instead.  This can be used by external callers to
           know whether to continue feeding input or not.
 
         The return value can be used to decide whether to use sys.ps1 or
         sys.ps2 to prompt the next line."""
 
         # if the source code has leading blanks, add 'if 1:\n' to it
         # this allows execution of indented pasted code. It is tempting
         # to add '\n' at the end of source to run commands like ' a=1'
         # directly, but this fails for more complicated scenarios
         source=source.encode(self.stdin_encoding)
         if source[:1] in [' ', '\t']:
             source = 'if 1:\n%s' % source
 
         try:
             code = self.compile(source,filename,symbol)
         except (OverflowError, SyntaxError, ValueError, TypeError):
             # Case 1
             self.showsyntaxerror(filename)
             return None
 
         if code is None:
             # Case 2
             return True
 
         # Case 3
         # We store the code object so that threaded shells and
         # custom exception handlers can access all this info if needed.
         # The source corresponding to this can be obtained from the
         # buffer attribute as '\n'.join(self.buffer).
         self.code_to_run = code
         # now actually execute the code object
         if self.runcode(code) == 0:
             return False
         else:
             return None
 
     def runcode(self,code_obj):
         """Execute a code object.
 
         When an exception occurs, self.showtraceback() is called to display a
         traceback.
 
         Return value: a flag indicating whether the code to be run completed
         successfully:
 
           - 0: successful execution.
           - 1: an error occurred.
         """
 
         # Set our own excepthook in case the user code tries to call it
         # directly, so that the IPython crash handler doesn't get triggered
         old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
 
         # we save the original sys.excepthook in the instance, in case config
         # code (such as magics) needs access to it.
         self.sys_excepthook = old_excepthook
         outflag = 1  # happens in more places, so it's easier as default
         try:
             try:
                 self.hooks.pre_runcode_hook()
                 exec code_obj in self.user_global_ns, self.user_ns
             finally:
                 # Reset our crash handler in place
                 sys.excepthook = old_excepthook
         except SystemExit:
             self.resetbuffer()
             self.showtraceback()
             warn("Type %exit or %quit to exit IPython "
                  "(%Exit or %Quit do so unconditionally).",level=1)
         except self.custom_exceptions:
             etype,value,tb = sys.exc_info()
             self.CustomTB(etype,value,tb)
         except:
             self.showtraceback()
         else:
             outflag = 0
             if softspace(sys.stdout, 0):
                 print
         # Flush out code object which has been run (and source)
         self.code_to_run = None
         return outflag
         
     def push(self, line):
         """Push a line to the interpreter.
 
         The line should not have a trailing newline; it may have
         internal newlines.  The line is appended to a buffer and the
         interpreter's runsource() method is called with the
         concatenated contents of the buffer as source.  If this
         indicates that the command was executed or invalid, the buffer
         is reset; otherwise, the command is incomplete, and the buffer
         is left as it was after the line was appended.  The return
         value is 1 if more input is required, 0 if the line was dealt
         with in some way (this is the same as runsource()).
         """
 
         # autoindent management should be done here, and not in the
         # interactive loop, since that one is only seen by keyboard input.  We
         # need this done correctly even for code run via runlines (which uses
         # push).
 
         #print 'push line: <%s>' % line  # dbg
         for subline in line.splitlines():
             self.autoindent_update(subline)
         self.buffer.append(line)
         more = self.runsource('\n'.join(self.buffer), self.filename)
         if not more:
             self.resetbuffer()
         return more
 
     def split_user_input(self, line):
         # This is really a hold-over to support ipapi and some extensions
         return prefilter.splitUserInput(line)
 
     def resetbuffer(self):
         """Reset the input buffer."""
         self.buffer[:] = []
         
     def raw_input(self,prompt='',continue_prompt=False):
         """Write a prompt and read a line.
 
         The returned line does not include the trailing newline.
         When the user enters the EOF key sequence, EOFError is raised.
 
         Optional inputs:
 
           - prompt(''): a string to be printed to prompt the user.
 
           - continue_prompt(False): whether this line is the first one or a
           continuation in a sequence of inputs.
         """
 
         # Code run by the user may have modified the readline completer state.
         # We must ensure that our completer is back in place.
         if self.has_readline:
             self.set_completer()
         
         try:
             line = raw_input_original(prompt).decode(self.stdin_encoding)
         except ValueError:
             warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
                  " or sys.stdout.close()!\nExiting IPython!")
             self.ask_exit()
             return ""
 
         # Try to be reasonably smart about not re-indenting pasted input more
         # than necessary.  We do this by trimming out the auto-indent initial
         # spaces, if the user's actual input started itself with whitespace.
         #debugx('self.buffer[-1]')
 
         if self.autoindent:
             if num_ini_spaces(line) > self.indent_current_nsp:
                 line = line[self.indent_current_nsp:]
                 self.indent_current_nsp = 0
             
         # store the unfiltered input before the user has any chance to modify
         # it.
         if line.strip():
             if continue_prompt:
                 self.input_hist_raw[-1] += '%s\n' % line
                 if self.has_readline: # and some config option is set?
                     try:
                         histlen = self.readline.get_current_history_length()
                         if histlen > 1:
                             newhist = self.input_hist_raw[-1].rstrip()
                             self.readline.remove_history_item(histlen-1)
                             self.readline.replace_history_item(histlen-2,
                                             newhist.encode(self.stdin_encoding))
                     except AttributeError:
                         pass # re{move,place}_history_item are new in 2.4.                
             else:
                 self.input_hist_raw.append('%s\n' % line)                
             # only entries starting at first column go to shadow history
             if line.lstrip() == line:
                 self.shadowhist.add(line.strip())
         elif not continue_prompt:
             self.input_hist_raw.append('\n')
         try:
             lineout = self.prefilter(line,continue_prompt)
         except:
             # blanket except, in case a user-defined prefilter crashes, so it
             # can't take all of ipython with it.
             self.showtraceback()
             return ''
         else:
             return lineout
 
     def _prefilter(self, line, continue_prompt):
         """Calls different preprocessors, depending on the form of line."""
 
         # All handlers *must* return a value, even if it's blank ('').
 
         # Lines are NOT logged here. Handlers should process the line as
         # needed, update the cache AND log it (so that the input cache array
         # stays synced).
 
         #.....................................................................
         # Code begins
 
         #if line.startswith('%crash'): raise RuntimeError,'Crash now!'  # dbg
 
         # save the line away in case we crash, so the post-mortem handler can
         # record it
         self._last_input_line = line
 
         #print '***line: <%s>' % line # dbg
 
         if not line:
             # Return immediately on purely empty lines, so that if the user
             # previously typed some whitespace that started a continuation
             # prompt, he can break out of that loop with just an empty line.
             # This is how the default python prompt works.
 
             # Only return if the accumulated input buffer was just whitespace!
             if ''.join(self.buffer).isspace():
                 self.buffer[:] = []
             return ''
         
         line_info = prefilter.LineInfo(line, continue_prompt)
         
         # the input history needs to track even empty lines
         stripped = line.strip()
         
         if not stripped:
             if not continue_prompt:
                 self.outputcache.prompt_count -= 1
             return self.handle_normal(line_info)
 
         # print '***cont',continue_prompt  # dbg
         # special handlers are only allowed for single line statements
         if continue_prompt and not self.rc.multi_line_specials:
             return self.handle_normal(line_info)
 
 
         # See whether any pre-existing handler can take care of it  
         rewritten = self.hooks.input_prefilter(stripped)
         if rewritten != stripped: # ok, some prefilter did something
             rewritten = line_info.pre + rewritten  # add indentation
             return self.handle_normal(prefilter.LineInfo(rewritten,
                                                          continue_prompt))
             
         #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest)  # dbg
         
         return prefilter.prefilter(line_info, self)
 
 
     def _prefilter_dumb(self, line, continue_prompt):
         """simple prefilter function, for debugging"""
         return self.handle_normal(line,continue_prompt)
 
     
     def multiline_prefilter(self, line, continue_prompt):
         """ Run _prefilter for each line of input
         
         Covers cases where there are multiple lines in the user entry,
         which is the case when the user goes back to a multiline history
         entry and presses enter.
         
         """
         out = []
         for l in line.rstrip('\n').split('\n'):
             out.append(self._prefilter(l, continue_prompt))
         return '\n'.join(out)
     
     # Set the default prefilter() function (this can be user-overridden)
     prefilter = multiline_prefilter
 
     def handle_normal(self,line_info):
         """Handle normal input lines. Use as a template for handlers."""
 
         # With autoindent on, we need some way to exit the input loop, and I
         # don't want to force the user to have to backspace all the way to
         # clear the line.  The rule will be in this case, that either two
         # lines of pure whitespace in a row, or a line of pure whitespace but
         # of a size different to the indent level, will exit the input loop.
         line = line_info.line
         continue_prompt = line_info.continue_prompt
         
         if (continue_prompt and self.autoindent and line.isspace() and
             (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
              (self.buffer[-1]).isspace() )):
             line = ''
 
         self.log(line,line,continue_prompt)
         return line
 
     def handle_alias(self,line_info):
         """Handle alias input lines. """
         tgt = self.alias_table[line_info.iFun]
         # print "=>",tgt #dbg
         if callable(tgt):
             if '$' in line_info.line:
                 call_meth = '(_ip, _ip.itpl(%s))'
             else:
                 call_meth = '(_ip,%s)'
             line_out = ("%s_sh.%s" + call_meth) % (line_info.preWhitespace,
                                          line_info.iFun, 
             make_quoted_expr(line_info.line))
         else:
             transformed = self.expand_aliases(line_info.iFun,line_info.theRest)
 
             # pre is needed, because it carries the leading whitespace.  Otherwise
             # aliases won't work in indented sections.
             line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
                                              make_quoted_expr( transformed ))
         
         self.log(line_info.line,line_out,line_info.continue_prompt)
         #print 'line out:',line_out # dbg
         return line_out
 
     def handle_shell_escape(self, line_info):
         """Execute the line in a shell, empty return value"""
         #print 'line in :', `line` # dbg
         line = line_info.line
         if line.lstrip().startswith('!!'):
             # rewrite LineInfo's line, iFun and theRest to properly hold the
             # call to %sx and the actual command to be executed, so
             # handle_magic can work correctly.  Note that this works even if
             # the line is indented, so it handles multi_line_specials
             # properly.
             new_rest = line.lstrip()[2:]
             line_info.line = '%ssx %s' % (self.ESC_MAGIC,new_rest)
             line_info.iFun = 'sx'
             line_info.theRest = new_rest
             return self.handle_magic(line_info)
         else:
             cmd = line.lstrip().lstrip('!')
             line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
                                              make_quoted_expr(cmd))
         # update cache/log and return
         self.log(line,line_out,line_info.continue_prompt)
         return line_out
 
     def handle_magic(self, line_info):
         """Execute magic functions."""
         iFun    = line_info.iFun
         theRest = line_info.theRest
         cmd = '%s_ip.magic(%s)' % (line_info.preWhitespace,
                                    make_quoted_expr(iFun + " " + theRest))
         self.log(line_info.line,cmd,line_info.continue_prompt)
         #print 'in handle_magic, cmd=<%s>' % cmd  # dbg
         return cmd
 
     def handle_auto(self, line_info):
         """Hande lines which can be auto-executed, quoting if requested."""
 
         line    = line_info.line
         iFun    = line_info.iFun
         theRest = line_info.theRest
         pre     = line_info.pre
         continue_prompt = line_info.continue_prompt
         obj = line_info.ofind(self)['obj']
 
         #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest)  # dbg
 
         # This should only be active for single-line input!
         if continue_prompt:
             self.log(line,line,continue_prompt)
             return line
 
         force_auto = isinstance(obj, IPython.ipapi.IPyAutocall)
         auto_rewrite = True
         
         if pre == self.ESC_QUOTE:
             # Auto-quote splitting on whitespace
             newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
         elif pre == self.ESC_QUOTE2:
             # Auto-quote whole string
             newcmd = '%s("%s")' % (iFun,theRest)
         elif pre == self.ESC_PAREN:
             newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
         else:
             # Auto-paren.
             # We only apply it to argument-less calls if the autocall
             # parameter is set to 2.  We only need to check that autocall is <
             # 2, since this function isn't called unless it's at least 1.
             if not theRest and (self.rc.autocall < 2) and not force_auto:
                 newcmd = '%s %s' % (iFun,theRest)
                 auto_rewrite = False
             else:
                 if not force_auto and theRest.startswith('['):
                     if hasattr(obj,'__getitem__'):
                         # Don't autocall in this case: item access for an object
                         # which is BOTH callable and implements __getitem__.
                         newcmd = '%s %s' % (iFun,theRest)
                         auto_rewrite = False
                     else:
                         # if the object doesn't support [] access, go ahead and
                         # autocall
                         newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
                 elif theRest.endswith(';'):
                     newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
                 else:
                     newcmd = '%s(%s)' % (iFun.rstrip(), theRest)
 
         if auto_rewrite:
             rw = self.outputcache.prompt1.auto_rewrite() + newcmd
             
             try:
                 # plain ascii works better w/ pyreadline, on some machines, so
                 # we use it and only print uncolored rewrite if we have unicode
                 rw = str(rw)
                 print >>Term.cout, rw
             except UnicodeEncodeError:
                 print "-------------->" + newcmd
             
         # log what is now valid Python, not the actual user input (without the
         # final newline)
         self.log(line,newcmd,continue_prompt)
         return newcmd
 
     def handle_help(self, line_info):
         """Try to get some help for the object.
 
         obj? or ?obj   -> basic information.
         obj?? or ??obj -> more details.
         """
         
         line = line_info.line
         # We need to make sure that we don't process lines which would be
         # otherwise valid python, such as "x=1 # what?"
         try:
             codeop.compile_command(line)
         except SyntaxError:
             # We should only handle as help stuff which is NOT valid syntax
             if line[0]==self.ESC_HELP:
                 line = line[1:]
             elif line[-1]==self.ESC_HELP:
                 line = line[:-1]
             self.log(line,'#?'+line,line_info.continue_prompt)
             if line:
                 #print 'line:<%r>' % line  # dbg
                 self.magic_pinfo(line)
             else:
                 page(self.usage,screen_lines=self.rc.screen_length)
             return '' # Empty string is needed here!
         except:
             # Pass any other exceptions through to the normal handler
             return self.handle_normal(line_info)
         else:
             # If the code compiles ok, we should handle it normally
             return self.handle_normal(line_info)
 
     def getapi(self):
         """ Get an IPApi object for this shell instance
         
         Getting an IPApi object is always preferable to accessing the shell
         directly, but this holds true especially for extensions.
         
         It should always be possible to implement an extension with IPApi
         alone. If not, contact maintainer to request an addition.
         
         """
         return self.api
 
     def handle_emacs(self, line_info):
         """Handle input lines marked by python-mode."""
 
         # Currently, nothing is done.  Later more functionality can be added
         # here if needed.
 
         # The input cache shouldn't be updated
         return line_info.line
     
 
     def mktempfile(self,data=None):
         """Make a new tempfile and return its filename.
 
         This makes a call to tempfile.mktemp, but it registers the created
         filename internally so ipython cleans it up at exit time.
 
         Optional inputs:
 
           - data(None): if data is given, it gets written out to the temp file
           immediately, and the file is closed again."""
 
         filename = tempfile.mktemp('.py','ipython_edit_')
         self.tempfiles.append(filename)
         
         if data:
             tmp_file = open(filename,'w')
             tmp_file.write(data)
             tmp_file.close()
         return filename
 
     def write(self,data):
         """Write a string to the default output"""
         Term.cout.write(data)
 
     def write_err(self,data):
         """Write a string to the default error output"""
         Term.cerr.write(data)
 
     def ask_exit(self):
         """ Call for exiting. Can be overiden and used as a callback. """
         self.exit_now = True
 
     def exit(self):
         """Handle interactive exit.
 
         This method calls the ask_exit callback."""
 
         if self.rc.confirm_exit:
             if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
                 self.ask_exit()
         else:
             self.ask_exit()
 
     def safe_execfile(self,fname,*where,**kw):
         """A safe version of the builtin execfile().
 
         This version will never throw an exception, and knows how to handle
         ipython logs as well.
 
         :Parameters:
           fname : string
             Name of the file to be executed.
             
           where : tuple
             One or two namespaces, passed to execfile() as (globals,locals).
             If only one is given, it is passed as both.
 
         :Keywords:
           islog : boolean (False)
 
           quiet : boolean (True)
 
           exit_ignore : boolean (False)
           """
 
         def syspath_cleanup():
             """Internal cleanup routine for sys.path."""
             if add_dname:
                 try:
                     sys.path.remove(dname)
                 except ValueError:
                     # For some reason the user has already removed it, ignore.
                     pass
         
         fname = os.path.expanduser(fname)
 
         # Find things also in current directory.  This is needed to mimic the
         # behavior of running a script from the system command line, where
         # Python inserts the script's directory into sys.path
         dname = os.path.dirname(os.path.abspath(fname))
         add_dname = False
         if dname not in sys.path:
             sys.path.insert(0,dname)
             add_dname = True
 
         try:
             xfile = open(fname)
         except:
             print >> Term.cerr, \
                   'Could not open file <%s> for safe execution.' % fname
             syspath_cleanup()
             return None
 
         kw.setdefault('islog',0)
         kw.setdefault('quiet',1)
         kw.setdefault('exit_ignore',0)
         
         first = xfile.readline()
         loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
         xfile.close()
         # line by line execution
         if first.startswith(loghead) or kw['islog']:
             print 'Loading log file <%s> one line at a time...' % fname
             if kw['quiet']:
                 stdout_save = sys.stdout
                 sys.stdout = StringIO.StringIO()
             try:
                 globs,locs = where[0:2]
             except:
                 try:
                     globs = locs = where[0]
                 except:
                     globs = locs = globals()
             badblocks = []
 
             # we also need to identify indented blocks of code when replaying
             # logs and put them together before passing them to an exec
             # statement. This takes a bit of regexp and look-ahead work in the
             # file. It's easiest if we swallow the whole thing in memory
             # first, and manually walk through the lines list moving the
             # counter ourselves.
             indent_re = re.compile('\s+\S')
             xfile = open(fname)
             filelines = xfile.readlines()
             xfile.close()
             nlines = len(filelines)
             lnum = 0
             while lnum < nlines:
                 line = filelines[lnum]
                 lnum += 1
                 # don't re-insert logger status info into cache
                 if line.startswith('#log#'):
                     continue
                 else:
                     # build a block of code (maybe a single line) for execution
                     block = line
                     try:
                         next = filelines[lnum] # lnum has already incremented
                     except:
                         next = None
                     while next and indent_re.match(next):
                         block += next
                         lnum += 1
                         try:
                             next = filelines[lnum]
                         except:
                             next = None
                     # now execute the block of one or more lines
                     try:
                         exec block in globs,locs
                     except SystemExit:
                         pass
                     except:
                         badblocks.append(block.rstrip())
             if kw['quiet']:  # restore stdout
                 sys.stdout.close()
                 sys.stdout = stdout_save
             print 'Finished replaying log file <%s>' % fname
             if badblocks:
                 print >> sys.stderr, ('\nThe following lines/blocks in file '
                                       '<%s> reported errors:' % fname)
                     
                 for badline in badblocks:
                     print >> sys.stderr, badline
         else:  # regular file execution
             try:
                 if sys.platform == 'win32' and sys.version_info < (2,5,1):
                     # Work around a bug in Python for Windows.  The bug was
                     # fixed in in Python 2.5 r54159 and 54158, but that's still
                     # SVN Python as of March/07.  For details, see:
                     # http://projects.scipy.org/ipython/ipython/ticket/123
                     try:
                         globs,locs = where[0:2]
                     except:
                         try:
                             globs = locs = where[0]
                         except:
                             globs = locs = globals()
                     exec file(fname) in globs,locs
                 else:
                     execfile(fname,*where)
             except SyntaxError:
                 self.showsyntaxerror()
                 warn('Failure executing file: <%s>' % fname)
             except SystemExit,status:
                 # Code that correctly sets the exit status flag to success (0)
                 # shouldn't be bothered with a traceback.  Note that a plain
                 # sys.exit() does NOT set the message to 0 (it's empty) so that
                 # will still get a traceback.  Note that the structure of the
                 # SystemExit exception changed between Python 2.4 and 2.5, so
                 # the checks must be done in a version-dependent way.
                 show = False
 
                 if sys.version_info[:2] > (2,5):
                     if status.message!=0 and not kw['exit_ignore']:
                         show = True
                 else:
                     if status.code and not kw['exit_ignore']:
                         show = True
                 if show:
                     self.showtraceback()
                     warn('Failure executing file: <%s>' % fname)
             except:
                 self.showtraceback()
                 warn('Failure executing file: <%s>' % fname)
 
         syspath_cleanup()
 
 #************************* end of file <iplib.py> *****************************

IPython/kernel/config/__init__.py

@@ -1,125 +1,124
 # encoding: utf-8
 
 """Default kernel configuration."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 
+from os.path import join as pjoin
+
 from IPython.external.configobj import ConfigObj
 from IPython.config.api import ConfigObjManager
-from IPython.config.cutils import get_ipython_dir
+from IPython.genutils import get_ipython_dir, get_security_dir
 
 default_kernel_config = ConfigObj()
 
-try:
-    ipython_dir = get_ipython_dir() + '/'
-except:
-    # This will defaults to the cwd
-    ipython_dir = ''
+security_dir = get_security_dir()
 
 #-------------------------------------------------------------------------------
 # Engine Configuration
 #-------------------------------------------------------------------------------
 
 engine_config = dict(
     logfile = '',    # Empty means log to stdout
-    furl_file = ipython_dir + 'ipcontroller-engine.furl'
+    furl_file = pjoin(security_dir, 'ipcontroller-engine.furl')
 )
 
 #-------------------------------------------------------------------------------
 # MPI Configuration
 #-------------------------------------------------------------------------------
 
 mpi_config = dict(
     mpi4py = """from mpi4py import MPI as mpi
 mpi.size = mpi.COMM_WORLD.Get_size()
 mpi.rank = mpi.COMM_WORLD.Get_rank()
 """,
     pytrilinos = """from PyTrilinos import Epetra
 class SimpleStruct:
     pass
 mpi = SimpleStruct()
 mpi.rank = 0
 mpi.size = 0
 """,
     default = ''
 )
 
 #-------------------------------------------------------------------------------
 # Controller Configuration
 #-------------------------------------------------------------------------------
 
 controller_config = dict(
 
     logfile = '',    # Empty means log to stdout
     import_statement = '',
+    reuse_furls = False, # If False, old furl files are deleted
 
     engine_tub = dict(
         ip = '',         # Empty string means all interfaces
         port = 0,        # 0 means pick a port for me
         location = '',    # Empty string means try to set automatically
         secure = True,
-        cert_file = ipython_dir + 'ipcontroller-engine.pem',
+        cert_file = pjoin(security_dir, 'ipcontroller-engine.pem'),
     ),
     engine_fc_interface = 'IPython.kernel.enginefc.IFCControllerBase',
-    engine_furl_file = ipython_dir + 'ipcontroller-engine.furl',
+    engine_furl_file = pjoin(security_dir, 'ipcontroller-engine.furl'),
     
     controller_interfaces = dict(
         # multiengine = dict(
         #     controller_interface = 'IPython.kernel.multiengine.IMultiEngine',
         #     fc_interface = 'IPython.kernel.multienginefc.IFCMultiEngine',
         #     furl_file = 'ipcontroller-mec.furl'
         # ),
         task = dict(
             controller_interface = 'IPython.kernel.task.ITaskController',
             fc_interface = 'IPython.kernel.taskfc.IFCTaskController',
-            furl_file = ipython_dir + 'ipcontroller-tc.furl'
+            furl_file = pjoin(security_dir, 'ipcontroller-tc.furl')
         ),
         multiengine = dict(
             controller_interface = 'IPython.kernel.multiengine.IMultiEngine',
             fc_interface = 'IPython.kernel.multienginefc.IFCSynchronousMultiEngine',
-            furl_file = ipython_dir + 'ipcontroller-mec.furl'
+            furl_file = pjoin(security_dir, 'ipcontroller-mec.furl')
         )
     ),
 
     client_tub = dict(
         ip = '',         # Empty string means all interfaces
         port = 0,        # 0 means pick a port for me
         location = '',    # Empty string means try to set automatically
         secure = True,
-        cert_file = ipython_dir + 'ipcontroller-client.pem'
+        cert_file = pjoin(security_dir, 'ipcontroller-client.pem')
     )
 )
 
 #-------------------------------------------------------------------------------
 # Client Configuration
 #-------------------------------------------------------------------------------
 
 client_config = dict(
     client_interfaces = dict(
         task = dict(
-            furl_file = ipython_dir + 'ipcontroller-tc.furl'
+            furl_file = pjoin(security_dir, 'ipcontroller-tc.furl')
         ),
         multiengine = dict(
-            furl_file = ipython_dir + 'ipcontroller-mec.furl'
+            furl_file = pjoin(security_dir, 'ipcontroller-mec.furl')
         )
     )
 )
 
 default_kernel_config['engine'] = engine_config
 default_kernel_config['mpi'] = mpi_config
 default_kernel_config['controller'] = controller_config
 default_kernel_config['client'] = client_config
 
 
 config_manager = ConfigObjManager(default_kernel_config, 'IPython.kernel.ini')
  No newline at end of file

IPython/kernel/contexts.py

@@ -1,143 +1,141
 # encoding: utf-8
 # -*- test-case-name: IPython.kernel.test.test_contexts -*-
 """Context managers for IPython.
 
 Python 2.5 introduced the `with` statement, which is based on the context
 manager protocol.  This module offers a few context managers for common cases,
 which can also be useful as templates for writing new, application-specific
 managers.
 """
 
-from __future__ import with_statement
-
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 linecache
 import sys
 
 from twisted.internet.error import ConnectionRefusedError
 
 from IPython.ultraTB import _fixed_getinnerframes, findsource
 from IPython import ipapi
 
 from IPython.kernel import error
 
 #---------------------------------------------------------------------------
 # Utility functions needed by all context managers.
 #---------------------------------------------------------------------------
 
 def remote():
     """Raises a special exception meant to be caught by context managers.
     """
     m = 'Special exception to stop local execution of parallel code.'
     raise error.StopLocalExecution(m)
 
 
 def strip_whitespace(source,require_remote=True):
     """strip leading whitespace from input source.
 
     :Parameters:
 
     """
     remote_mark = 'remote()'
     # Expand tabs to avoid any confusion.
     wsource = [l.expandtabs(4) for l in source]
     # Detect the indentation level
     done = False
     for line in wsource:
         if line.isspace():
             continue
         for col,char in enumerate(line):
             if char != ' ':
                 done = True
                 break
         if done:
             break
     # Now we know how much leading space there is in the code.  Next, we
     # extract up to the first line that has less indentation.
     # WARNINGS: we skip comments that may be misindented, but we do NOT yet
     # detect triple quoted strings that may have flush left text.
     for lno,line in enumerate(wsource):
         lead = line[:col]
         if lead.isspace():
             continue
         else:
             if not lead.lstrip().startswith('#'):
                 break
     # The real 'with' source is up to lno
     src_lines = [l[col:] for l in wsource[:lno+1]]
 
     # Finally, check that the source's first non-comment line begins with the
     # special call 'remote()'
     if require_remote:
         for nline,line in enumerate(src_lines):
             if line.isspace() or line.startswith('#'):
                 continue
             if line.startswith(remote_mark):
                 break
             else:
                 raise ValueError('%s call missing at the start of code' %
                                  remote_mark)
         out_lines = src_lines[nline+1:]
     else:
         # If the user specified that the remote() call wasn't mandatory
         out_lines = src_lines
 
     # src = ''.join(out_lines)  # dbg
     #print 'SRC:\n<<<<<<<>>>>>>>\n%s<<<<<>>>>>>' % src  # dbg
     return ''.join(out_lines)
 
 class RemoteContextBase(object):
     def __init__(self):
         self.ip = ipapi.get()
 
     def _findsource_file(self,f):
         linecache.checkcache()
         s = findsource(f.f_code)
         lnum = f.f_lineno
         wsource = s[0][f.f_lineno:]
         return strip_whitespace(wsource)
 
     def _findsource_ipython(self,f):
         from IPython import ipapi
         self.ip = ipapi.get()
         buf = self.ip.IP.input_hist_raw[-1].splitlines()[1:]
         wsource = [l+'\n' for l in buf ]
 
         return strip_whitespace(wsource)
 
     def findsource(self,frame):
         local_ns = frame.f_locals
         global_ns = frame.f_globals
         if frame.f_code.co_filename == '<ipython console>':
             src = self._findsource_ipython(frame)
         else:
             src = self._findsource_file(frame)
         return src
 
     def __enter__(self):
         raise NotImplementedError
 
     def __exit__ (self, etype, value, tb):
         if issubclass(etype,error.StopLocalExecution):
             return True
 
 class RemoteMultiEngine(RemoteContextBase):
     def __init__(self,mec):
         self.mec = mec
         RemoteContextBase.__init__(self)
 
     def __enter__(self):
         src = self.findsource(sys._getframe(1))
         return self.mec.execute(src)

IPython/kernel/controllerservice.py

@@ -1,376 +1,376
 # encoding: utf-8
 # -*- test-case-name: IPython.kernel.test.test_controllerservice -*-
 
 """A Twisted Service for the IPython Controller.
 
 The IPython Controller:
 
 * Listens for Engines to connect and then manages access to those engines.
 * Listens for clients and passes commands from client to the Engines.
 * Exposes an asynchronous interfaces to the Engines which themselves can block.
 * Acts as a gateway to the Engines.
 
 The design of the controller is somewhat abstract to allow flexibility in how 
 the controller is presented to clients.  This idea is that there is a basic
 ControllerService class that allows engines to connect to it.  But, this 
 basic class has no client interfaces.  To expose client interfaces developers
 provide an adapter that makes the ControllerService look like something.  For 
 example, one client interface might support task farming and another might
 support interactive usage.  The important thing is that by using interfaces
 and adapters, a single controller can be accessed from multiple interfaces.
 Furthermore, by adapting various client interfaces to various network
 protocols, each client interface can be exposed to multiple network protocols.
 See multiengine.py for an example of how to adapt the ControllerService
 to a client interface.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 os, sys
 
 from twisted.application import service
 from twisted.internet import defer, reactor
 from twisted.python import log, components
 from zope.interface import Interface, implements, Attribute
 import zope.interface as zi
 
 from IPython.kernel.engineservice import \
     IEngineCore, \
     IEngineSerialized, \
     IEngineQueued
     
-from IPython.config import cutils
+from IPython.genutils import get_ipython_dir
 from IPython.kernel import codeutil
 
 #-------------------------------------------------------------------------------
 # Interfaces for the Controller
 #-------------------------------------------------------------------------------
 
 class IControllerCore(Interface):
     """Basic methods any controller must have.
     
     This is basically the aspect of the controller relevant to the 
     engines and does not assume anything about how the engines will
     be presented to a client.
     """
         
     engines = Attribute("A dict of engine ids and engine instances.")
         
     def register_engine(remoteEngine, id=None, ip=None, port=None, 
         pid=None):
         """Register new remote engine.
         
         The controller can use the ip, port, pid of the engine to do useful things
         like kill the engines.
         
         :Parameters:
             remoteEngine
                 An implementer of IEngineCore, IEngineSerialized and IEngineQueued.
             id : int
                 Requested id.
             ip : str
                 IP address the engine is running on.
             port : int
                 Port the engine is on.
             pid : int
                 pid of the running engine.
         
         :Returns: A dict of {'id':id} and possibly other key, value pairs.
         """
     
     def unregister_engine(id):
         """Handle a disconnecting engine.
         
         :Parameters:
             id
                 The integer engine id of the engine to unregister.
         """
         
     def on_register_engine_do(f, includeID, *args, **kwargs):
         """Call ``f(*args, **kwargs)`` when an engine is registered.
         
         :Parameters:
             includeID : int
                 If True the first argument to f will be the id of the engine.
         """
             
     def on_unregister_engine_do(f, includeID, *args, **kwargs):
         """Call ``f(*args, **kwargs)`` when an engine is unregistered.
         
         :Parameters:
             includeID : int
                 If True the first argument to f will be the id of the engine.
         """
     
     def on_register_engine_do_not(f):
         """Stop calling f on engine registration"""
     
     def on_unregister_engine_do_not(f):
         """Stop calling f on engine unregistration"""
         
     def on_n_engines_registered_do(n, f, *arg, **kwargs):
         """Call f(*args, **kwargs) the first time the nth engine registers."""
                     
 class IControllerBase(IControllerCore):
     """The basic controller interface."""
     pass 
 
 
 #-------------------------------------------------------------------------------
 # Implementation of the ControllerService
 #-------------------------------------------------------------------------------
 
 class ControllerService(object, service.Service):
     """A basic Controller represented as a Twisted Service.
     
     This class doesn't implement any client notification mechanism.  That
     is up to adapted subclasses.
     """
     
     # I also pick up the IService interface by inheritance from service.Service
     implements(IControllerBase)
     name = 'ControllerService'
     
     def __init__(self, maxEngines=511, saveIDs=False):
         self.saveIDs = saveIDs
         self.engines = {}
         self.availableIDs = range(maxEngines,-1,-1)   # [511,...,0]
         self._onRegister = []
         self._onUnregister = []
         self._onNRegistered = []
     
     #---------------------------------------------------------------------------
     # Methods used to save the engine info to a log file
     #---------------------------------------------------------------------------
     
     def _buildEngineInfoString(self, id, ip, port, pid):
         if id is None:
             id = -99
         if ip is None:
             ip = "-99"
         if port is None:
             port = -99
         if pid is None:
             pid = -99
         return "Engine Info: %d %s %d %d" % (id, ip , port, pid)
         
     def _logEngineInfo(self, id, ip, port, pid):
         log.msg(self._buildEngineInfoString(id,ip,port,pid))
     
     def _getEngineInfoLogFile(self):
         # Store all logs inside the ipython directory
-        ipdir = cutils.get_ipython_dir()
+        ipdir = get_ipython_dir()
         pjoin = os.path.join
         logdir_base = pjoin(ipdir,'log')
         if not os.path.isdir(logdir_base):
             os.makedirs(logdir_base)
         logfile = os.path.join(logdir_base,'ipcontroller-%s-engine-info.log' % os.getpid())
         return logfile
     
     def _logEngineInfoToFile(self, id, ip, port, pid):
         """Log info about an engine to a log file.
         
         When an engine registers with a ControllerService, the ControllerService
         saves information about the engine to a log file.  That information
         can be useful for various purposes, such as killing hung engines, etc.
         
         This method takes the assigned id, ip/port and pid of the engine
         and saves it to a file of the form:
         
         ~/.ipython/log/ipcontroller-###-engine-info.log
         
         where ### is the pid of the controller.
         
         Each line of this file has the form:
         
         Engine Info: ip ip port pid
         
         If any of the entries are not known, they are replaced by -99.
         """
         
         fname = self._getEngineInfoLogFile()
         f = open(fname, 'a')
         s = self._buildEngineInfoString(id,ip,port,pid)
         f.write(s + '\n')
         f.close()
     
     #---------------------------------------------------------------------------
     # IControllerCore methods
     #---------------------------------------------------------------------------
         
     def register_engine(self, remoteEngine, id=None,
         ip=None, port=None, pid=None):
         """Register new engine connection"""
         
         # What happens if these assertions fail?
         assert IEngineCore.providedBy(remoteEngine), \
             "engine passed to register_engine doesn't provide IEngineCore"
         assert IEngineSerialized.providedBy(remoteEngine), \
             "engine passed to register_engine doesn't provide IEngineSerialized"
         assert IEngineQueued.providedBy(remoteEngine), \
             "engine passed to register_engine doesn't provide IEngineQueued"
         assert isinstance(id, int) or id is None, \
             "id to register_engine must be an integer or None"
         assert isinstance(ip, str) or ip is None, \
             "ip to register_engine must be a string or None"
         assert isinstance(port, int) or port is None, \
             "port to register_engine must be an integer or None"
         assert isinstance(pid, int) or pid is None, \
             "pid to register_engine must be an integer or None"
             
         desiredID = id
         if desiredID in self.engines.keys():
             desiredID = None
             
         if desiredID in self.availableIDs:
             getID = desiredID
             self.availableIDs.remove(desiredID)
         else:
             getID = self.availableIDs.pop()
         remoteEngine.id = getID
         remoteEngine.service = self
         self.engines[getID] = remoteEngine
 
         # Log the Engine Information for monitoring purposes
         self._logEngineInfoToFile(getID, ip, port, pid)
 
         msg = "registered engine with id: %i" %getID
         log.msg(msg)
         
         for i in range(len(self._onRegister)):
             (f,args,kwargs,ifid) = self._onRegister[i]
             try:
                 if ifid:
                     f(getID, *args, **kwargs)
                 else:
                     f(*args, **kwargs)
             except:
                 self._onRegister.pop(i)
         
         # Call functions when the nth engine is registered and them remove them
         for i, (n, f, args, kwargs) in enumerate(self._onNRegistered):
             if len(self.engines.keys()) == n:
                 try:
                     try:
                         f(*args, **kwargs)
                     except:
                         log.msg("Function %r failed when the %ith engine registered" % (f, n))
                 finally:
                     self._onNRegistered.pop(i)
         
         return {'id':getID}
     
     def unregister_engine(self, id):
         """Unregister engine by id."""
         
         assert isinstance(id, int) or id is None, \
             "id to unregister_engine must be an integer or None"
         
         msg = "unregistered engine with id: %i" %id
         log.msg(msg)
         try:
             del self.engines[id]
         except KeyError:
             log.msg("engine with id %i was not registered" % id)
         else:
             if not self.saveIDs:
                 self.availableIDs.append(id)
                 # Sort to assign lower ids first
                 self.availableIDs.sort(reverse=True) 
             else:
                 log.msg("preserving id %i" %id)
             
             for i in range(len(self._onUnregister)):
                 (f,args,kwargs,ifid) = self._onUnregister[i]
                 try:
                     if ifid:
                         f(id, *args, **kwargs)
                     else:
                         f(*args, **kwargs)
                 except:
                     self._onUnregister.pop(i)
     
     def on_register_engine_do(self, f, includeID, *args, **kwargs):
         assert callable(f), "f must be callable"
         self._onRegister.append((f,args,kwargs,includeID))
 
     def on_unregister_engine_do(self, f, includeID, *args, **kwargs):
         assert callable(f), "f must be callable"
         self._onUnregister.append((f,args,kwargs,includeID))
     
     def on_register_engine_do_not(self, f):
         for i in range(len(self._onRegister)):
             g = self._onRegister[i][0]
             if f == g:
                 self._onRegister.pop(i)
                 return
     
     def on_unregister_engine_do_not(self, f):
         for i in range(len(self._onUnregister)):
             g = self._onUnregister[i][0]
             if f == g:
                 self._onUnregister.pop(i)
                 return
 
     def on_n_engines_registered_do(self, n, f, *args, **kwargs):
         if len(self.engines.keys()) >= n:
             f(*args, **kwargs)
         else:
             self._onNRegistered.append((n,f,args,kwargs))
             
 
 #-------------------------------------------------------------------------------
 # Base class for adapting controller to different client APIs
 #-------------------------------------------------------------------------------
 
 class ControllerAdapterBase(object):
     """All Controller adapters should inherit from this class.
     
     This class provides a wrapped version of the IControllerBase interface that
     can be used to easily create new custom controllers.  Subclasses of this
     will provide a full implementation of IControllerBase.
     
     This class doesn't implement any client notification mechanism.  That
     is up to subclasses.
     """
     
     implements(IControllerBase)
     
     def __init__(self, controller):
         self.controller = controller
         # Needed for IControllerCore
         self.engines = self.controller.engines
         
     def register_engine(self, remoteEngine, id=None,
         ip=None, port=None, pid=None):
         return self.controller.register_engine(remoteEngine, 
             id, ip, port, pid)
     
     def unregister_engine(self, id):
         return self.controller.unregister_engine(id)
 
     def on_register_engine_do(self, f, includeID, *args, **kwargs):
         return self.controller.on_register_engine_do(f, includeID, *args, **kwargs)
 
     def on_unregister_engine_do(self, f, includeID, *args, **kwargs):
         return self.controller.on_unregister_engine_do(f, includeID, *args, **kwargs)        
     
     def on_register_engine_do_not(self, f):
         return self.controller.on_register_engine_do_not(f)
     
     def on_unregister_engine_do_not(self, f):
         return self.controller.on_unregister_engine_do_not(f)        
 
     def on_n_engines_registered_do(self, n, f, *args, **kwargs):
         return self.controller.on_n_engines_registered_do(n, f, *args, **kwargs)

IPython/kernel/core/interpreter.py

@@ -1,747 +1,754
 # encoding: utf-8
 
 """Central interpreter object for an IPython engine.
 
 The interpreter is the object whose job is to process lines of user input and
 actually execute them in the user's namespace.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 # Standard library imports.
 from types import FunctionType
 
 import __builtin__
 import codeop
 import compiler
 import sys
 import traceback
 
 # Local imports.
 from IPython.kernel.core import ultraTB
 from IPython.kernel.core.display_trap import DisplayTrap
 from IPython.kernel.core.macro import Macro
 from IPython.kernel.core.prompts import CachedOutput
 from IPython.kernel.core.traceback_trap import TracebackTrap
 from IPython.kernel.core.util import Bunch, system_shell
 from IPython.external.Itpl import ItplNS
 
 # Global constants
 COMPILER_ERROR = 'error'
 INCOMPLETE_INPUT = 'incomplete'
 COMPLETE_INPUT = 'complete'
 
 ##############################################################################
 # TEMPORARY!!! fake configuration, while we decide whether to use tconfig or
 # not
 
 rc = Bunch()
 rc.cache_size = 100
 rc.pprint = True
 rc.separate_in = '\n'
 rc.separate_out = '\n'
 rc.separate_out2 = ''
 rc.prompt_in1 = r'In [\#]: '
 rc.prompt_in2 = r'   .\\D.: '
 rc.prompt_out = ''
 rc.prompts_pad_left = False
 
 ##############################################################################
 
 # Top-level utilities
 def default_display_formatters():
     """ Return a list of default display formatters.
     """
 
     from display_formatter import PPrintDisplayFormatter, ReprDisplayFormatter
     return [PPrintDisplayFormatter(), ReprDisplayFormatter()]
 
 def default_traceback_formatters():
     """ Return a list of default traceback formatters.
     """
 
     from traceback_formatter import PlainTracebackFormatter
     return [PlainTracebackFormatter()]
 
 # Top-level classes
 class NotDefined(object):    pass
 
 class Interpreter(object):
     """ An interpreter object.
 
     fixme: needs to negotiate available formatters with frontends.
 
     Important: the interpeter should be built so that it exposes a method
     for each attribute/method of its sub-object. This way it can be
     replaced by a network adapter.
     """
 
     def __init__(self, user_ns=None, global_ns=None,translator=None,
                  magic=None, display_formatters=None,
                  traceback_formatters=None, output_trap=None, history=None,
                  message_cache=None, filename='<string>', config=None):
 
         # The local/global namespaces for code execution
         local_ns = user_ns  # compatibility name
         if local_ns is None:
             local_ns = {}
         self.user_ns = local_ns
         # The local namespace
         if global_ns is None:
             global_ns = {}
         self.user_global_ns = global_ns
 
         # An object that will translate commands into executable Python.
         # The current translator does not work properly so for now we are going
         # without!
         # if translator is None:
         #             from IPython.kernel.core.translator import IPythonTranslator
         #             translator = IPythonTranslator()
         self.translator = translator
 
         # An object that maintains magic commands.
         if magic is None:
             from IPython.kernel.core.magic import Magic
             magic = Magic(self)
         self.magic = magic
 
         # A list of formatters for the displayhook.
         if display_formatters is None:
             display_formatters = default_display_formatters()
         self.display_formatters = display_formatters
 
         # A list of formatters for tracebacks.
         if traceback_formatters is None:
             traceback_formatters = default_traceback_formatters()
         self.traceback_formatters = traceback_formatters
 
         # The object trapping stdout/stderr.
         if output_trap is None:
             from IPython.kernel.core.output_trap import OutputTrap
             output_trap = OutputTrap()
         self.output_trap = output_trap
 
         # An object that manages the history.
         if history is None:
             from IPython.kernel.core.history import InterpreterHistory
             history = InterpreterHistory()
         self.history = history
         self.get_history_item = history.get_history_item
         self.get_history_input_cache = history.get_input_cache
         self.get_history_input_after = history.get_input_after
 
         # An object that caches all of the return messages.
         if message_cache is None:
             from IPython.kernel.core.message_cache import SimpleMessageCache
             message_cache = SimpleMessageCache()
         self.message_cache = message_cache
 
         # The "filename" of the code that is executed in this interpreter.
         self.filename = filename
 
         # An object that contains much configuration information.
         if config is None:
             # fixme: Move this constant elsewhere!
             config = Bunch(ESC_MAGIC='%')
         self.config = config
 
         # Hook managers.
         # fixme: make the display callbacks configurable. In the meantime,
         # enable macros.
         self.display_trap = DisplayTrap(
             formatters=self.display_formatters,
             callbacks=[self._possible_macro],
         )
         self.traceback_trap = TracebackTrap(
             formatters=self.traceback_formatters)
 
         # This is used temporarily for reformating exceptions in certain
         # cases.  It will go away once the ultraTB stuff is ported
         # to ipython1
         self.tbHandler = ultraTB.FormattedTB(color_scheme='NoColor',
                                                  mode='Context',
                                                  tb_offset=2)
 
         # An object that can compile commands and remember __future__
         # statements.
         self.command_compiler = codeop.CommandCompiler()
 
         # A replacement for the raw_input() and input() builtins. Change these
         # attributes later to configure them.
         self.raw_input_builtin = raw_input
         self.input_builtin = input
 
         # The number of the current cell.
         self.current_cell_number = 1
 
         # Initialize cache, set in/out prompts and printing system
         self.outputcache = CachedOutput(self,
                                         rc.cache_size,
                                         rc.pprint,
                                         input_sep = rc.separate_in,
                                         output_sep = rc.separate_out,
                                         output_sep2 = rc.separate_out2,
                                         ps1 = rc.prompt_in1,
                                         ps2 = rc.prompt_in2,
                                         ps_out = rc.prompt_out,
                                         pad_left = rc.prompts_pad_left)
 
         # Need to decide later if this is the right approach, but clients
         # commonly use sys.ps1/2, so it may be best to just set them here
         sys.ps1 = self.outputcache.prompt1.p_str
         sys.ps2 = self.outputcache.prompt2.p_str
 
         # This is the message dictionary assigned temporarily when running the
         # code.
         self.message = None
 
         self.setup_namespace()
 
 
     #### Public 'Interpreter' interface ########################################
 
     def formatTraceback(self, et, ev, tb, message=''):
         """Put a formatted version of the traceback into value and reraise.
         
         When exceptions have to be sent over the network, the traceback 
         needs to be put into the value of the exception in a nicely
         formatted way.  The method takes the type, value and tb of an 
         exception and puts a string representation of the tb into the 
         value of the exception and reraises it.
         
         Currently this method uses the ultraTb formatter from IPython trunk.
         Eventually it should simply use the traceback formatters in core
         that are loaded into self.tracback_trap.formatters.
         """
         tbinfo = self.tbHandler.text(et,ev,tb)
         ev._ipython_traceback_text = tbinfo
         return et, ev, tb
         
     def execute(self, commands, raiseException=True):
         """ Execute some IPython commands.
 
         1. Translate them into Python.
         2. Run them.
         3. Trap stdout/stderr.
         4. Trap sys.displayhook().
         5. Trap exceptions.
         6. Return a message object.
 
         Parameters
         ----------
         commands : str
             The raw commands that the user typed into the prompt.
         
         Returns
         -------
         message : dict
             The dictionary of responses. See the README.txt in this directory
             for an explanation of the format.
         """
 
         # Create a message dictionary with all of the information we will be
         # returning to the frontend and other listeners.
         message = self.setup_message()
 
         # Massage the input and store the raw and translated commands into
         # a dict.
         user_input = dict(raw=commands)
         if self.translator is not None:
             python = self.translator(commands, message)
             if python is None:
                 # Something went wrong with the translation. The translator
                 # should have added an appropriate entry to the message object.
                 return message
         else:
             python = commands
         user_input['translated'] = python
         message['input'] = user_input
 
         # Set the message object so that any magics executed in the code have
         # access.
         self.message = message
 
         # Set all of the output/exception traps.
         self.set_traps()
         
         # Actually execute the Python code.
         status = self.execute_python(python)
 
         # Unset all of the traps.
         self.unset_traps()
 
         # Unset the message object.
         self.message = None
 
         # Update the history variables in the namespace.
         # E.g. In, Out, _, __, ___
         if self.history is not None:
             self.history.update_history(self, python)
 
         # Let all of the traps contribute to the message and then clear their
         # stored information.
         self.output_trap.add_to_message(message)
         self.output_trap.clear()
         self.display_trap.add_to_message(message)
         self.display_trap.clear()
         self.traceback_trap.add_to_message(message)
         # Pull out the type, value and tb of the current exception
         # before clearing it.
         einfo = self.traceback_trap.args
         self.traceback_trap.clear()
         
         # Cache the message.
         self.message_cache.add_message(self.current_cell_number, message)
 
         # Bump the number.
         self.current_cell_number += 1
         
         # This conditional lets the execute method either raise any
         # exception that has occured in user code OR return the message
         # dict containing the traceback and other useful info.
         if raiseException and einfo:
             raise einfo[0],einfo[1],einfo[2]
         else:
             return message
 
     def generate_prompt(self, is_continuation):
         """Calculate and return a string with the prompt to display.
 
         :Parameters:
           is_continuation : bool
             Whether the input line is continuing multiline input or not, so
           that a proper continuation prompt can be computed."""
         
         if is_continuation:
             return str(self.outputcache.prompt2)
         else:
             return str(self.outputcache.prompt1)
 
     def execute_python(self, python):
         """ Actually run the Python code in the namespace.
 
         :Parameters:
 
         python : str
             Pure, exec'able Python code. Special IPython commands should have
             already been translated into pure Python.
         """
 
         # We use a CommandCompiler instance to compile the code so as to keep
         # track of __future__ imports.
         try:
             commands = self.split_commands(python)
         except (SyntaxError, IndentationError), e:
             # Save the exc_info so compilation related exceptions can be
             # reraised
             self.traceback_trap.args = sys.exc_info()
             self.pack_exception(self.message,e)
             return None
 
         for cmd in commands:
             try:
                 code = self.command_compiler(cmd, self.filename, 'single')
             except (SyntaxError, OverflowError, ValueError), e:
                 self.traceback_trap.args = sys.exc_info()
                 self.pack_exception(self.message,e)
                 # No point in continuing if one block raised
                 return None
             else:
                 self.execute_block(code)
 
     def execute_block(self,code):
         """Execute a single block of code in the user namespace.
 
         Return value: a flag indicating whether the code to be run completed
         successfully:
 
           - 0: successful execution.
           - 1: an error occurred.
           """
         
         outflag = 1 # start by assuming error, success will reset it
         try:
             exec code in self.user_ns
             outflag = 0
         except SystemExit:
             self.resetbuffer()
             self.traceback_trap.args = sys.exc_info()
         except:
             self.traceback_trap.args = sys.exc_info()
 
         return outflag
 
     def execute_macro(self, macro):
         """ Execute the value of a macro.
 
         Parameters
         ----------
         macro : Macro
         """
 
         python = macro.value
         if self.translator is not None:
             python = self.translator(python)
         self.execute_python(python)
 
     def getCommand(self, i=None):
         """Gets the ith message in the message_cache.
         
         This is implemented here for compatibility with the old ipython1 shell
         I am not sure we need this though.  I even seem to remember that we
         were going to get rid of it.
         """
         return self.message_cache.get_message(i)
 
     def reset(self):
         """Reset the interpreter.
         
         Currently this only resets the users variables in the namespace.
         In the future we might want to also reset the other stateful
         things like that the Interpreter has, like In, Out, etc.
         """
         self.user_ns.clear()
         self.setup_namespace()
 
     def complete(self,line,text=None, pos=None):
         """Complete the given text.
 
         :Parameters:
 
           text : str
             Text fragment to be completed on.  Typically this is
         """
         # fixme: implement
         raise NotImplementedError
 
     def push(self, ns):
         """ Put value into the namespace with name key.
         
         Parameters
         ----------
         **kwds
         """
 
         self.user_ns.update(ns)
 
     def push_function(self, ns):
         # First set the func_globals for all functions to self.user_ns
         new_kwds = {}
         for k, v in ns.iteritems():
             if not isinstance(v, FunctionType):
                 raise TypeError("function object expected")
             new_kwds[k] = FunctionType(v.func_code, self.user_ns)
         self.user_ns.update(new_kwds)        
 
     def pack_exception(self,message,exc):
         message['exception'] = exc.__class__
         message['exception_value'] = \
             traceback.format_exception_only(exc.__class__, exc)
 
     def feed_block(self, source, filename='<input>', symbol='single'):
         """Compile some source in the interpreter.
 
         One several things can happen:
 
         1) The input is incorrect; compile_command() raised an
         exception (SyntaxError or OverflowError).
 
         2) The input is incomplete, and more input is required;
         compile_command() returned None.  Nothing happens.
 
         3) The input is complete; compile_command() returned a code
         object.  The code is executed by calling self.runcode() (which
         also handles run-time exceptions, except for SystemExit).
 
         The return value is:
 
           - True in case 2
 
           - False in the other cases, unless an exception is raised, where
           None is returned instead.  This can be used by external callers to
           know whether to continue feeding input or not.
 
         The return value can be used to decide whether to use sys.ps1 or
         sys.ps2 to prompt the next line."""
 
         self.message = self.setup_message()
 
         try:
             code = self.command_compiler(source,filename,symbol)
         except (OverflowError, SyntaxError, IndentationError, ValueError ), e:
             # Case 1
             self.traceback_trap.args = sys.exc_info()
             self.pack_exception(self.message,e)
             return COMPILER_ERROR,False
 
         if code is None:
             # Case 2: incomplete input.  This means that the input can span
             # multiple lines.  But we still need to decide when to actually
             # stop taking user input.  Later we'll add auto-indentation support
             # somehow.  In the meantime, we'll just stop if there are two lines
             # of pure whitespace at the end.
             last_two = source.rsplit('\n',2)[-2:]
             print 'last two:',last_two  # dbg
             if len(last_two)==2 and all(s.isspace() for s in last_two):
                 return COMPLETE_INPUT,False
             else:
                 return INCOMPLETE_INPUT, True
         else:
             # Case 3
             return COMPLETE_INPUT, False
         
     def pull(self, keys):
         """ Get an item out of the namespace by key.
         
         Parameters
         ----------
         key : str
 
         Returns
         -------
         value : object
 
         Raises
         ------
         TypeError if the key is not a string.
         NameError if the object doesn't exist.
         """
 
         if isinstance(keys, str):
             result = self.user_ns.get(keys, NotDefined())
             if isinstance(result, NotDefined):
                 raise NameError('name %s is not defined' % keys)        
         elif isinstance(keys, (list, tuple)):
             result = []
             for key in keys:
                 if not isinstance(key, str):
                     raise TypeError("objects must be keyed by strings.")
                 else:
                     r = self.user_ns.get(key, NotDefined())
                     if isinstance(r, NotDefined):
                         raise NameError('name %s is not defined' % key)
                     else:
                         result.append(r)
                     if len(keys)==1:
                         result = result[0]
         else:
             raise TypeError("keys must be a strong or a list/tuple of strings")
         return result
 
     def pull_function(self, keys):
         return self.pull(keys)
 
     #### Interactive user API ##################################################
 
     def ipsystem(self, command):
         """ Execute a command in a system shell while expanding variables in the
         current namespace.
 
         Parameters
         ----------
         command : str
         """
 
         # Expand $variables.
         command = self.var_expand(command)
 
         system_shell(command,
             header='IPython system call: ',
             verbose=self.rc.system_verbose,
         )
 
     def ipmagic(self, arg_string):
         """ Call a magic function by name.
 
         ipmagic('name -opt foo bar') is equivalent to typing at the ipython
         prompt:
 
         In[1]: %name -opt foo bar
 
         To call a magic without arguments, simply use ipmagic('name').
 
         This provides a proper Python function to call IPython's magics in any
         valid Python code you can type at the interpreter, including loops and
         compound statements.  It is added by IPython to the Python builtin
         namespace upon initialization.
 
         Parameters
         ----------
         arg_string : str
             A string containing the name of the magic function to call and any
             additional arguments to be passed to the magic.
 
         Returns
         -------
         something : object
             The return value of the actual object.
         """
 
         # Taken from IPython.
         raise NotImplementedError('Not ported yet')
 
         args = arg_string.split(' ', 1)
         magic_name = args[0]
         magic_name = magic_name.lstrip(self.config.ESC_MAGIC)
 
         try:
             magic_args = args[1]
         except IndexError:
             magic_args = ''
         fn = getattr(self.magic, 'magic_'+magic_name, None)
         if fn is None:
             self.error("Magic function `%s` not found." % magic_name)
         else:
             magic_args = self.var_expand(magic_args)
             return fn(magic_args)
 
 
     #### Private 'Interpreter' interface #######################################
 
     def setup_message(self):
         """Return a message object.
 
         This method prepares and returns a message dictionary.  This dict
         contains the various fields that are used to transfer information about
         execution, results, tracebacks, etc, to clients (either in or out of
         process ones).  Because of the need to work with possibly out of
         process clients, this dict MUST contain strictly pickle-safe values.
         """
 
         return dict(number=self.current_cell_number)
     
     def setup_namespace(self):
         """ Add things to the namespace.
         """
 
         self.user_ns.setdefault('__name__', '__main__')
         self.user_ns.setdefault('__builtins__', __builtin__)
         self.user_ns['__IP'] = self
         if self.raw_input_builtin is not None:
             self.user_ns['raw_input'] = self.raw_input_builtin
         if self.input_builtin is not None:
             self.user_ns['input'] = self.input_builtin
 
         builtin_additions = dict(
             ipmagic=self.ipmagic,
         )
         __builtin__.__dict__.update(builtin_additions)
 
         if self.history is not None:
             self.history.setup_namespace(self.user_ns)
 
     def set_traps(self):
         """ Set all of the output, display, and traceback traps.
         """
 
         self.output_trap.set()
         self.display_trap.set()
         self.traceback_trap.set()
 
     def unset_traps(self):
         """ Unset all of the output, display, and traceback traps.
         """
 
         self.output_trap.unset()
         self.display_trap.unset()
         self.traceback_trap.unset()
 
     def split_commands(self, python):
         """ Split multiple lines of code into discrete commands that can be
         executed singly.
 
         Parameters
         ----------
         python : str
             Pure, exec'able Python code.
 
         Returns
         -------
         commands : list of str
             Separate commands that can be exec'ed independently.
         """
 
         # compiler.parse treats trailing spaces after a newline as a
         # SyntaxError.  This is different than codeop.CommandCompiler, which
         # will compile the trailng spaces just fine.  We simply strip any
         # trailing whitespace off.  Passing a string with trailing whitespace
         # to exec will fail however.  There seems to be some inconsistency in
         # how trailing whitespace is handled, but this seems to work.
         python = python.strip()
 
+        # The compiler module does not like unicode. We need to convert
+        # it encode it:
+        if isinstance(python, unicode):
+            # Use the utf-8-sig BOM so the compiler detects this a UTF-8
+            # encode string.
+            python = '\xef\xbb\xbf' + python.encode('utf-8')
+
         # The compiler module will parse the code into an abstract syntax tree.
         ast = compiler.parse(python)
 
         # Uncomment to help debug the ast tree
         # for n in ast.node:
         #     print n.lineno,'->',n
                 
         # Each separate command is available by iterating over ast.node. The
         # lineno attribute is the line number (1-indexed) beginning the commands
         # suite.
         # lines ending with ";" yield a Discard Node that doesn't have a lineno
         # attribute.  These nodes can and should be discarded.  But there are
         # other situations that cause Discard nodes that shouldn't be discarded.
         # We might eventually discover other cases where lineno is None and have
         # to put in a more sophisticated test.
         linenos = [x.lineno-1 for x in ast.node if x.lineno is not None]
 
         # When we finally get the slices, we will need to slice all the way to
         # the end even though we don't have a line number for it. Fortunately,
         # None does the job nicely.
         linenos.append(None)
         lines = python.splitlines()
 
         # Create a list of atomic commands.
         cmds = []
         for i, j in zip(linenos[:-1], linenos[1:]):
             cmd = lines[i:j]
             if cmd:
                 cmds.append('\n'.join(cmd)+'\n')
 
         return cmds
 
     def error(self, text):
         """ Pass an error message back to the shell.
 
         Preconditions
         -------------
         This should only be called when self.message is set. In other words,
         when code is being executed.
 
         Parameters
         ----------
         text : str
         """
 
         errors = self.message.get('IPYTHON_ERROR', [])
         errors.append(text)
 
     def var_expand(self, template):
         """ Expand $variables in the current namespace using Itpl.
 
         Parameters
         ----------
         template : str
         """
 
         return str(ItplNS(template, self.user_ns))
 
     def _possible_macro(self, obj):
         """ If the object is a macro, execute it.
         """
 
         if isinstance(obj, Macro):
             self.execute_macro(obj)
 

IPython/kernel/core/tests/test_redirectors.py

@@ -1,61 +1,70
 # encoding: utf-8
 """
 Test the output capture at the OS level, using file descriptors.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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.
 #-------------------------------------------------------------------------------
 
 
+# Stdlib imports
 import os
 from cStringIO import StringIO
 
+# Our own imports
+from IPython.testing import decorators as dec
 
+#-----------------------------------------------------------------------------
+# Test functions
+
[e-mail]_win32
 def test_redirector():
     """ Checks that the redirector can be used to do synchronous capture.
     """
     from IPython.kernel.core.fd_redirector import FDRedirector
     r = FDRedirector()
     out = StringIO()
     try:
         r.start()
         for i in range(10):
             os.system('echo %ic' % i)
             print >>out, r.getvalue(),
             print >>out, i
     except:
         r.stop()
         raise
     r.stop()
-    assert out.getvalue() == "".join("%ic\n%i\n" %(i, i) for i in range(10))
+    result1 = out.getvalue()
+    result2 = "".join("%ic\n%i\n" %(i, i) for i in range(10))
+    assert result1 == result2
 
 
[e-mail]_win32
 def test_redirector_output_trap():
     """ This test check not only that the redirector_output_trap does
         trap the output, but also that it does it in a gready way, that
         is by calling the callback ASAP.
     """
     from IPython.kernel.core.redirector_output_trap import RedirectorOutputTrap
     out = StringIO()
     trap = RedirectorOutputTrap(out.write, out.write)
     try:
         trap.set()
         for i in range(10):
             os.system('echo %ic' % i)
             print "%ip" % i
             print >>out, i
     except:
         trap.unset()
         raise
     trap.unset()
-    assert out.getvalue() == "".join("%ic\n%ip\n%i\n" %(i, i, i) 
-                                                    for i in range(10))
-
+    result1 = out.getvalue()
+    result2 = "".join("%ic\n%ip\n%i\n" %(i, i, i) for i in range(10))
+    assert result1 == result2
     
-

IPython/kernel/engineconnector.py

@@ -1,87 +1,92
 # encoding: utf-8
 
 """A class that manages the engines connection to the controller."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 os
 import cPickle as pickle
 
-from twisted.python import log
+from twisted.python import log, failure
+from twisted.internet import defer
 
 from IPython.kernel.fcutil import find_furl
 from IPython.kernel.enginefc import IFCEngine
 
 #-------------------------------------------------------------------------------
 # The ClientConnector class
 #-------------------------------------------------------------------------------
 
 class EngineConnector(object):
     """Manage an engines connection to a controller.
     
     This class takes a foolscap `Tub` and provides a `connect_to_controller` 
     method that will use the `Tub` to connect to a controller and register
     the engine with the controller.
     """
     
     def __init__(self, tub):
         self.tub = tub
         
     def connect_to_controller(self, engine_service, furl_or_file):
         """
         Make a connection to a controller specified by a furl.
         
         This method takes an `IEngineBase` instance and a foolcap URL and uses
         the `tub` attribute to make a connection to the controller.  The 
         foolscap URL contains all the information needed to connect to the 
         controller, including the ip and port as well as any encryption and 
         authentication information needed for the connection.
         
         After getting a reference to the controller, this method calls the 
         `register_engine` method of the controller to actually register the 
         engine.
         
         :Parameters:
             engine_service : IEngineBase
                 An instance of an `IEngineBase` implementer
             furl_or_file : str
                 A furl or a filename containing a furl
         """
         if not self.tub.running:
             self.tub.startService()
         self.engine_service = engine_service
         self.engine_reference = IFCEngine(self.engine_service)
-        self.furl = find_furl(furl_or_file)
+        try:
+            self.furl = find_furl(furl_or_file)
+        except ValueError:
+            return defer.fail(failure.Failure())
+            # return defer.fail(failure.Failure(ValueError('not a valid furl or furl file: %r' % furl_or_file)))
         d = self.tub.getReference(self.furl)
         d.addCallbacks(self._register, self._log_failure)
         return d
     
     def _log_failure(self, reason):
-        log.err('engine registration failed:')
+        log.err('EngineConnector: engine registration failed:')
         log.err(reason)
         return reason
 
     def _register(self, rr):
         self.remote_ref = rr
         # Now register myself with the controller
         desired_id = self.engine_service.id
         d = self.remote_ref.callRemote('register_engine', self.engine_reference, 
             desired_id, os.getpid(), pickle.dumps(self.engine_service.properties,2))
         return d.addCallbacks(self._reference_sent, self._log_failure)
 
     def _reference_sent(self, registration_dict):
         self.engine_service.id = registration_dict['id']
         log.msg("engine registration succeeded, got id: %r" % self.engine_service.id)
         return self.engine_service.id
 

IPython/kernel/scripts/ipcluster.py

@@ -1,324 +1,486
 #!/usr/bin/env python
 # encoding: utf-8
 
-"""Start an IPython cluster conveniently, either locally or remotely.
+"""Start an IPython cluster = (controller + engines)."""
 
-Basic usage
------------
-
-For local operation, the simplest mode of usage is:
-
-  %prog -n N
-
-where N is the number of engines you want started.
-
-For remote operation, you must call it with a cluster description file:
-
-  %prog -f clusterfile.py
-
-The cluster file is a normal Python script which gets run via execfile().  You
-can have arbitrary logic in it, but all that matters is that at the end of the
-execution, it declares the variables 'controller', 'engines', and optionally
-'sshx'.  See the accompanying examples for details on what these variables must
-contain.
-
-
-Notes
------
-
-WARNING: this code is still UNFINISHED and EXPERIMENTAL!  It is incomplete,
-some listed options are not really implemented, and all of its interfaces are
-subject to change.
-
-When operating over SSH for a remote cluster, this program relies on the
-existence of a particular script called 'sshx'.  This script must live in the
-target systems where you'll be running your controller and engines, and is
-needed to configure your PATH and PYTHONPATH variables for further execution of
-python code at the other end of an SSH connection.  The script can be as simple
-as:
-
-#!/bin/sh
-. $HOME/.bashrc
-"$@"
-
-which is the default one provided by IPython.  You can modify this or provide
-your own.  Since it's quite likely that for different clusters you may need
-this script to configure things differently or that it may live in different
-locations, its full path can be set in the same file where you define the
-cluster setup.  IPython's order of evaluation for this variable is the
-following:
-
-  a) Internal default: 'sshx'.  This only works if it is in the default system
-  path which SSH sets up in non-interactive mode.
-
-  b) Environment variable: if $IPYTHON_SSHX is defined, this overrides the
-  internal default.
-
-  c) Variable 'sshx' in the cluster configuration file: finally, this will
-  override the previous two values.
- 
-This code is Unix-only, with precious little hope of any of this ever working
-under Windows, since we need SSH from the ground up, we background processes,
-etc.  Ports of this functionality to Windows are welcome.
-
-
-Call summary
-------------
-
-    %prog [options]
-"""
-
-__docformat__ = "restructuredtext en"
-
-#-------------------------------------------------------------------------------
+#-----------------------------------------------------------------------------
 #  Copyright (C) 2008  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.
-#-------------------------------------------------------------------------------
+#-----------------------------------------------------------------------------
 
-#-------------------------------------------------------------------------------
-# Stdlib imports
-#-------------------------------------------------------------------------------
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
 
 import os
-import signal
+import re
 import sys
-import time
+import signal
+pjoin = os.path.join
 
-from optparse import OptionParser
-from subprocess import Popen,call
+from twisted.internet import reactor, defer
+from twisted.internet.protocol import ProcessProtocol
+from twisted.python import failure, log
+from twisted.internet.error import ProcessDone, ProcessTerminated
+from twisted.internet.utils import getProcessOutput
 
-#---------------------------------------------------------------------------
-# IPython imports
-#---------------------------------------------------------------------------
-from IPython.tools import utils
-from IPython.config import cutils
+from IPython.external import argparse
+from IPython.external import Itpl
+from IPython.kernel.twistedutil import gatherBoth
+from IPython.kernel.util import printer
+from IPython.genutils import get_ipython_dir, num_cpus
 
-#---------------------------------------------------------------------------
-# Normal code begins
-#---------------------------------------------------------------------------
+#-----------------------------------------------------------------------------
+# General process handling code
+#-----------------------------------------------------------------------------
 
-def parse_args():
-    """Parse command line and return opts,args."""
+def find_exe(cmd):
+    try:
+        import win32api
+    except ImportError:
+        raise ImportError('you need to have pywin32 installed for this to work')
+    else:
+        (path, offest) = win32api.SearchPath(os.environ['PATH'],cmd)
+        return path
 
-    parser = OptionParser(usage=__doc__)
-    newopt = parser.add_option  # shorthand
+class ProcessStateError(Exception):
+    pass
 
-    newopt("--controller-port", type="int", dest="controllerport",
-           help="the TCP port the controller is listening on")
+class UnknownStatus(Exception):
+    pass
 
-    newopt("--controller-ip", type="string", dest="controllerip",
-           help="the TCP ip address of the controller")
+class LauncherProcessProtocol(ProcessProtocol):
+    """
+    A ProcessProtocol to go with the ProcessLauncher.
+    """
+    def __init__(self, process_launcher):
+        self.process_launcher = process_launcher
+    
+    def connectionMade(self):
+        self.process_launcher.fire_start_deferred(self.transport.pid)
+    
+    def processEnded(self, status):
+        value = status.value
+        if isinstance(value, ProcessDone):
+            self.process_launcher.fire_stop_deferred(0)
+        elif isinstance(value, ProcessTerminated):
+            self.process_launcher.fire_stop_deferred(
+                {'exit_code':value.exitCode,
+                 'signal':value.signal,
+                 'status':value.status
+                }
+            )
+        else:
+            raise UnknownStatus("unknown exit status, this is probably a bug in Twisted")
 
-    newopt("-n", "--num", type="int", dest="n",default=2,
-           help="the number of engines to start")
+    def outReceived(self, data):
+        log.msg(data)
 
-    newopt("--engine-port", type="int", dest="engineport",
-           help="the TCP port the controller will listen on for engine "
-           "connections")
-    
-    newopt("--engine-ip", type="string", dest="engineip",
-           help="the TCP ip address the controller will listen on "
-           "for engine connections")
+    def errReceived(self, data):
+        log.err(data)
 
-    newopt("--mpi", type="string", dest="mpi",
-           help="use mpi with package:  for instance --mpi=mpi4py")
+class ProcessLauncher(object):
+    """
+    Start and stop an external process in an asynchronous manner.
+    
+    Currently this uses deferreds to notify other parties of process state
+    changes.  This is an awkward design and should be moved to using
+    a formal NotificationCenter.
+    """
+    def __init__(self, cmd_and_args):
+        self.cmd = cmd_and_args[0]
+        self.args = cmd_and_args
+        self._reset()
+    
+    def _reset(self):
+        self.process_protocol = None
+        self.pid = None
+        self.start_deferred = None
+        self.stop_deferreds = []
+        self.state = 'before' # before, running, or after
     
-    newopt("-l", "--logfile", type="string", dest="logfile",
-           help="log file name")
+    @property
+    def running(self):
+        if self.state == 'running':
+            return True
+        else:
+            return False
+    
+    def fire_start_deferred(self, pid):
+        self.pid = pid
+        self.state = 'running'
+        log.msg('Process %r has started with pid=%i' % (self.args, pid))
+        self.start_deferred.callback(pid)
+    
+    def start(self):
+        if self.state == 'before':
+            self.process_protocol = LauncherProcessProtocol(self)
+            self.start_deferred = defer.Deferred()
+            self.process_transport = reactor.spawnProcess(
+                self.process_protocol,
+                self.cmd,
+                self.args,
+                env=os.environ
+            )
+            return self.start_deferred
+        else:
+            s = 'the process has already been started and has state: %r' % \
+                self.state
+            return defer.fail(ProcessStateError(s))
+    
+    def get_stop_deferred(self):
+        if self.state == 'running' or self.state == 'before':
+            d = defer.Deferred()
+            self.stop_deferreds.append(d)
+            return d
+        else:
+            s = 'this process is already complete'
+            return defer.fail(ProcessStateError(s))
+    
+    def fire_stop_deferred(self, exit_code):
+        log.msg('Process %r has stopped with %r' % (self.args, exit_code))
+        self.state = 'after'
+        for d in self.stop_deferreds:
+            d.callback(exit_code)
+    
+    def signal(self, sig):
+        """
+        Send a signal to the process.
+        
+        The argument sig can be ('KILL','INT', etc.) or any signal number.
+        """
+        if self.state == 'running':
+            self.process_transport.signalProcess(sig)
+    
+    # def __del__(self):
+    #     self.signal('KILL')
+    
+    def interrupt_then_kill(self, delay=1.0):
+        self.signal('INT')
+        reactor.callLater(delay, self.signal, 'KILL')
 
-    newopt('-f','--cluster-file',dest='clusterfile',
-           help='file describing a remote cluster')
 
-    return parser.parse_args()
+#-----------------------------------------------------------------------------
+# Code for launching controller and engines
+#-----------------------------------------------------------------------------
 
-def numAlive(controller,engines):
-    """Return the number of processes still alive."""
-    retcodes = [controller.poll()] + \
-               [e.poll() for e in engines]
-    return retcodes.count(None)
 
-stop = lambda pid: os.kill(pid,signal.SIGINT)
-kill = lambda pid: os.kill(pid,signal.SIGTERM)
+class ControllerLauncher(ProcessLauncher):
+    
+    def __init__(self, extra_args=None):
+        if sys.platform == 'win32':
+            args = [find_exe('ipcontroller.bat')]
+        else:
+            args = ['ipcontroller']
+        self.extra_args = extra_args
+        if extra_args is not None:
+            args.extend(extra_args)
+        
+        ProcessLauncher.__init__(self, args)
+
 
-def cleanup(clean,controller,engines):
-    """Stop the controller and engines with the given cleanup method."""
+class EngineLauncher(ProcessLauncher):
     
-    for e in engines:
-        if e.poll() is None:
-            print 'Stopping engine, pid',e.pid
-            clean(e.pid)
-    if controller.poll() is None:
-        print 'Stopping controller, pid',controller.pid
-        clean(controller.pid)
-
-
-def ensureDir(path):
-    """Ensure a directory exists or raise an exception."""
-    if not os.path.isdir(path):
-        os.makedirs(path)
-
-
-def startMsg(control_host,control_port=10105):
-    """Print a startup message"""
-    print
-    print 'Your cluster is up and running.'
-    print
-    print 'For interactive use, you can make a MultiEngineClient with:'
-    print
-    print 'from IPython.kernel import client'
-    print "mec = client.MultiEngineClient()"
-    print
-    print 'You can then cleanly stop the cluster from IPython using:'
-    print
-    print 'mec.kill(controller=True)'
-    print
+    def __init__(self, extra_args=None):
+        if sys.platform == 'win32':
+            args = [find_exe('ipengine.bat')]
+        else:
+            args = ['ipengine']
+        self.extra_args = extra_args
+        if extra_args is not None:
+            args.extend(extra_args)
+        
+        ProcessLauncher.__init__(self, args)
 
+
+class LocalEngineSet(object):
     
-def clusterLocal(opt,arg):
-    """Start a cluster on the local machine."""
+    def __init__(self, extra_args=None):
+        self.extra_args = extra_args
+        self.launchers = []
     
-    # Store all logs inside the ipython directory
-    ipdir = cutils.get_ipython_dir()
-    pjoin = os.path.join
-
-    logfile = opt.logfile
-    if logfile is None:
-        logdir_base = pjoin(ipdir,'log')
-        ensureDir(logdir_base)
-        logfile = pjoin(logdir_base,'ipcluster-')
-
-    print 'Starting controller:',
-    controller = Popen(['ipcontroller','--logfile',logfile,'-x','-y'])
-    print 'Controller PID:',controller.pid
-
-    print 'Starting engines:   ',
-    time.sleep(5)
-
-    englogfile = '%s%s-' % (logfile,controller.pid)
-    mpi = opt.mpi
-    if mpi: # start with mpi - killing the engines with sigterm will not work if you do this
-        engines = [Popen(['mpirun', '-np', str(opt.n), 'ipengine', '--mpi', 
-            mpi, '--logfile',englogfile])]
-        # engines = [Popen(['mpirun', '-np', str(opt.n), 'ipengine', '--mpi', mpi])]
-    else: # do what we would normally do
-        engines = [ Popen(['ipengine','--logfile',englogfile])
-                    for i in range(opt.n) ]
-    eids = [e.pid for e in engines]
-    print 'Engines PIDs:  ',eids
-    print 'Log files: %s*' % englogfile
+    def start(self, n):
+        dlist = []
+        for i in range(n):
+            el = EngineLauncher(extra_args=self.extra_args)
+            d = el.start()
+            self.launchers.append(el)
+            dlist.append(d)
+        dfinal = gatherBoth(dlist, consumeErrors=True)
+        dfinal.addCallback(self._handle_start)
+        return dfinal
     
-    proc_ids = eids + [controller.pid]
-    procs = engines + [controller]
-
-    grpid = os.getpgrp()
-    try:
-        startMsg('127.0.0.1')
-        print 'You can also hit Ctrl-C to stop it, or use from the cmd line:'
-        print
-        print 'kill -INT',grpid
-        print
-        try:
-            while True:
-                time.sleep(5)
-        except:
-            pass
-    finally:
-        print 'Stopping cluster.  Cleaning up...'
-        cleanup(stop,controller,engines)
-        for i in range(4):
-            time.sleep(i+2)
-            nZombies = numAlive(controller,engines)
-            if  nZombies== 0:
-                print 'OK: All processes cleaned up.'
-                break
-            print 'Trying again, %d processes did not stop...' % nZombies
-            cleanup(kill,controller,engines)
-            if numAlive(controller,engines) == 0:
-                print 'OK: All processes cleaned up.'
-                break
-        else:
-            print '*'*75
-            print 'ERROR: could not kill some processes, try to do it',
-            print 'manually.'
-            zombies = []
-            if controller.returncode is None:
-                print 'Controller is alive: pid =',controller.pid
-                zombies.append(controller.pid)
-            liveEngines = [ e for e in engines if e.returncode is None ]
-            for e in liveEngines:
-                print 'Engine is alive:     pid =',e.pid
-                zombies.append(e.pid)
-            print
-            print 'Zombie summary:',' '.join(map(str,zombies))
-
-def clusterRemote(opt,arg):
-    """Start a remote cluster over SSH"""
-
-    # Load the remote cluster configuration
-    clConfig = {}
-    execfile(opt.clusterfile,clConfig)
-    contConfig = clConfig['controller']
-    engConfig = clConfig['engines']
-    # Determine where to find sshx:
-    sshx = clConfig.get('sshx',os.environ.get('IPYTHON_SSHX','sshx'))
+    def _handle_start(self, r):
+        log.msg('Engines started with pids: %r' % r)
+        return r
     
-    # Store all logs inside the ipython directory
-    ipdir = cutils.get_ipython_dir()
-    pjoin = os.path.join
-
-    logfile = opt.logfile
-    if logfile is None:
-        logdir_base = pjoin(ipdir,'log')
-        ensureDir(logdir_base)
-        logfile = pjoin(logdir_base,'ipcluster')
-
-    # Append this script's PID to the logfile name always
-    logfile = '%s-%s' % (logfile,os.getpid())
+    def _handle_stop(self, r):
+        log.msg('Engines received signal: %r' % r)
+        return r
     
-    print 'Starting controller:'
-    # Controller data:
-    xsys = os.system
-
-    contHost = contConfig['host']
-    contLog = '%s-con-%s-' % (logfile,contHost)
-    cmd = "ssh %s '%s' 'ipcontroller --logfile %s' &" % \
-          (contHost,sshx,contLog)
-    #print 'cmd:<%s>' % cmd  # dbg
-    xsys(cmd)
-    time.sleep(2)
-
-    print 'Starting engines:   '
-    for engineHost,engineData in engConfig.iteritems():
-        if isinstance(engineData,int):
-            numEngines = engineData
+    def signal(self, sig):
+        dlist = []
+        for el in self.launchers:
+            d = el.get_stop_deferred()
+            dlist.append(d)
+            el.signal(sig)
+        dfinal = gatherBoth(dlist, consumeErrors=True)
+        dfinal.addCallback(self._handle_stop)
+        return dfinal
+    
+    def interrupt_then_kill(self, delay=1.0):
+        dlist = []
+        for el in self.launchers:
+            d = el.get_stop_deferred()
+            dlist.append(d)
+            el.interrupt_then_kill(delay)
+        dfinal = gatherBoth(dlist, consumeErrors=True)
+        dfinal.addCallback(self._handle_stop)
+        return dfinal
+
+
+class BatchEngineSet(object):
+    
+    # Subclasses must fill these in.  See PBSEngineSet
+    submit_command = ''
+    delete_command = ''
+    job_id_regexp = ''
+    
+    def __init__(self, template_file, **kwargs):
+        self.template_file = template_file
+        self.context = {}
+        self.context.update(kwargs)
+        self.batch_file = self.template_file+'-run'
+
+    def parse_job_id(self, output):
+        m = re.match(self.job_id_regexp, output)
+        if m is not None:
+            job_id = m.group()
         else:
-            raise NotImplementedError('port configuration not finished for engines')
-
-        print 'Sarting %d engines on %s' % (numEngines,engineHost)
-        engLog = '%s-eng-%s-' % (logfile,engineHost)
-        for i in range(numEngines):
-            cmd = "ssh %s '%s' 'ipengine --controller-ip %s --logfile %s' &" % \
-                      (engineHost,sshx,contHost,engLog)
-            #print 'cmd:<%s>' % cmd  # dbg
-            xsys(cmd)
-        # Wait after each host a little bit
-        time.sleep(1)
-            
-    startMsg(contConfig['host'])
+            raise Exception("job id couldn't be determined: %s" % output)
+        self.job_id = job_id
+        log.msg('Job started with job id: %r' % job_id)
+        return job_id
+    
+    def write_batch_script(self, n):
+        self.context['n'] = n
+        template = open(self.template_file, 'r').read()
+        log.msg('Using template for batch script: %s' % self.template_file)
+        script_as_string = Itpl.itplns(template, self.context)
+        log.msg('Writing instantiated batch script: %s' % self.batch_file)
+        f = open(self.batch_file,'w')
+        f.write(script_as_string)
+        f.close()
+
+    def handle_error(self, f):
+        f.printTraceback()
+        f.raiseException()
+    
+    def start(self, n):
+        self.write_batch_script(n)
+        d = getProcessOutput(self.submit_command,
+            [self.batch_file],env=os.environ)
+        d.addCallback(self.parse_job_id)
+        d.addErrback(self.handle_error)
+        return d
         
-def main():
-    """Main driver for the two big options: local or remote cluster."""
+    def kill(self):
+        d = getProcessOutput(self.delete_command,
+            [self.job_id],env=os.environ)
+        return d
+
+class PBSEngineSet(BatchEngineSet):
+    
+    submit_command = 'qsub'
+    delete_command = 'qdel'
+    job_id_regexp = '\d+'
     
-    opt,arg = parse_args()
+    def __init__(self, template_file, **kwargs):
+        BatchEngineSet.__init__(self, template_file, **kwargs)
+
+
+#-----------------------------------------------------------------------------
+# Main functions for the different types of clusters
+#-----------------------------------------------------------------------------
+
+# TODO:
+# The logic in these codes should be moved into classes like LocalCluster
+# MpirunCluster, PBSCluster, etc.  This would remove alot of the duplications.
+# The main functions should then just parse the command line arguments, create
+# the appropriate class and call a 'start' method.
+
+def main_local(args):
+    cont_args = []
+    cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
+    if args.x:
+        cont_args.append('-x')
+    if args.y:
+        cont_args.append('-y')
+    cl = ControllerLauncher(extra_args=cont_args)
+    dstart = cl.start()
+    def start_engines(cont_pid):
+        engine_args = []
+        engine_args.append('--logfile=%s' % \
+            pjoin(args.logdir,'ipengine%s-' % cont_pid))
+        eset = LocalEngineSet(extra_args=engine_args)
+        def shutdown(signum, frame):
+            log.msg('Stopping local cluster')
+            # We are still playing with the times here, but these seem
+            # to be reliable in allowing everything to exit cleanly.
+            eset.interrupt_then_kill(0.5)
+            cl.interrupt_then_kill(0.5)
+            reactor.callLater(1.0, reactor.stop)
+        signal.signal(signal.SIGINT,shutdown)
+        d = eset.start(args.n)
+        return d
+    def delay_start(cont_pid):
+        # This is needed because the controller doesn't start listening
+        # right when it starts and the controller needs to write
+        # furl files for the engine to pick up
+        reactor.callLater(1.0, start_engines, cont_pid)
+    dstart.addCallback(delay_start)
+    dstart.addErrback(lambda f: f.raiseException())
+
+def main_mpirun(args):
+    cont_args = []
+    cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
+    if args.x:
+        cont_args.append('-x')
+    if args.y:
+        cont_args.append('-y')
+    cl = ControllerLauncher(extra_args=cont_args)
+    dstart = cl.start()
+    def start_engines(cont_pid):
+        raw_args = ['mpirun']
+        raw_args.extend(['-n',str(args.n)])
+        raw_args.append('ipengine')
+        raw_args.append('-l')
+        raw_args.append(pjoin(args.logdir,'ipengine%s-' % cont_pid))
+        if args.mpi:
+            raw_args.append('--mpi=%s' % args.mpi)
+        eset = ProcessLauncher(raw_args)
+        def shutdown(signum, frame):
+            log.msg('Stopping local cluster')
+            # We are still playing with the times here, but these seem
+            # to be reliable in allowing everything to exit cleanly.
+            eset.interrupt_then_kill(1.0)
+            cl.interrupt_then_kill(1.0)
+            reactor.callLater(2.0, reactor.stop)
+        signal.signal(signal.SIGINT,shutdown)
+        d = eset.start()
+        return d
+    def delay_start(cont_pid):
+        # This is needed because the controller doesn't start listening
+        # right when it starts and the controller needs to write
+        # furl files for the engine to pick up
+        reactor.callLater(1.0, start_engines, cont_pid)
+    dstart.addCallback(delay_start)
+    dstart.addErrback(lambda f: f.raiseException())
+
+def main_pbs(args):
+    cont_args = []
+    cont_args.append('--logfile=%s' % pjoin(args.logdir,'ipcontroller'))
+    if args.x:
+	cont_args.append('-x')
+    if args.y:
+	cont_args.append('-y')
+    cl = ControllerLauncher(extra_args=cont_args)
+    dstart = cl.start()
+    def start_engines(r):
+        pbs_set =  PBSEngineSet(args.pbsscript)
+        def shutdown(signum, frame):
+            log.msg('Stopping pbs cluster')
+            d = pbs_set.kill()
+            d.addBoth(lambda _: cl.interrupt_then_kill(1.0))
+            d.addBoth(lambda _: reactor.callLater(2.0, reactor.stop))
+        signal.signal(signal.SIGINT,shutdown)
+        d = pbs_set.start(args.n)
+        return d
+    dstart.addCallback(start_engines)
+    dstart.addErrback(lambda f: f.raiseException())
+
+
+def get_args():
+    base_parser = argparse.ArgumentParser(add_help=False)
+    base_parser.add_argument(
+        '-x',
+        action='store_true',
+        dest='x',
+        help='turn off client security'
+    )
+    base_parser.add_argument(
+        '-y',
+        action='store_true',
+        dest='y',
+        help='turn off engine security'
+    )
+    base_parser.add_argument(
+        "--logdir", 
+        type=str,
+        dest="logdir",
+        help="directory to put log files (default=$IPYTHONDIR/log)",
+        default=pjoin(get_ipython_dir(),'log')
+    )
+    base_parser.add_argument(
+        "-n",
+        "--num", 
+        type=int,
+        dest="n",
+        default=2,
+        help="the number of engines to start"
+    )
+    
+    parser = argparse.ArgumentParser(
+        description='IPython cluster startup.  This starts a controller and\
+        engines using various approaches.  THIS IS A TECHNOLOGY PREVIEW AND\
+        THE API WILL CHANGE SIGNIFICANTLY BEFORE THE FINAL RELEASE.'
+    )
+    subparsers = parser.add_subparsers(
+        help='available cluster types.  For help, do "ipcluster TYPE --help"')
+    
+    parser_local = subparsers.add_parser(
+        'local',
+        help='run a local cluster',
+        parents=[base_parser]
+    )
+    parser_local.set_defaults(func=main_local)
+    
+    parser_mpirun = subparsers.add_parser(
+        'mpirun',
+        help='run a cluster using mpirun',
+        parents=[base_parser]
+    )
+    parser_mpirun.add_argument(
+        "--mpi",
+        type=str,
+        dest="mpi", # Don't put a default here to allow no MPI support
+        help="how to call MPI_Init (default=mpi4py)"
+    )
+    parser_mpirun.set_defaults(func=main_mpirun)
+    
+    parser_pbs = subparsers.add_parser(
+        'pbs', 
+        help='run a pbs cluster',
+        parents=[base_parser]
+    )
+    parser_pbs.add_argument(
+        '--pbs-script',
+        type=str, 
+        dest='pbsscript',
+        help='PBS script template',
+        default='pbs.template'
+    )
+    parser_pbs.set_defaults(func=main_pbs)
+    args = parser.parse_args()
+    return args
 
-    clusterfile = opt.clusterfile
-    if clusterfile:
-        clusterRemote(opt,arg)
-    else:
-        clusterLocal(opt,arg)
-        
-            
-if __name__=='__main__':
+def main():
+    args = get_args()
+    reactor.callWhenRunning(args.func, args)
+    log.startLogging(sys.stdout)
+    reactor.run()
+
+if __name__ == '__main__':
     main()

IPython/kernel/scripts/ipcontroller.py

@@ -1,366 +1,388
 #!/usr/bin/env python
 # encoding: utf-8
 
 """The IPython controller."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 # Python looks for an empty string at the beginning of sys.path to enable
 # importing from the cwd.
 import sys
 sys.path.insert(0, '')
 
 import sys, time, os
 from optparse import OptionParser
 
 from twisted.application import internet, service
 from twisted.internet import reactor, error, defer
 from twisted.python import log
 
 from IPython.kernel.fcutil import Tub, UnauthenticatedTub, have_crypto
 
 # from IPython.tools import growl
 # growl.start("IPython1 Controller")
 
 from IPython.kernel.error import SecurityError
 from IPython.kernel import controllerservice
 from IPython.kernel.fcutil import check_furl_file_security
 
 from IPython.kernel.config import config_manager as kernel_config_manager
 from IPython.config.cutils import import_item
 
 
 #-------------------------------------------------------------------------------
 # Code
 #-------------------------------------------------------------------------------
 
 def make_tub(ip, port, secure, cert_file):
     """
     Create a listening tub given an ip, port, and cert_file location.
     
     :Parameters:
         ip : str
             The ip address that the tub should listen on.  Empty means all
         port : int
             The port that the tub should listen on.  A value of 0 means
             pick a random port
         secure: boolean
             Will the connection be secure (in the foolscap sense)
         cert_file:
             A filename of a file to be used for theSSL certificate
     """
     if secure:
         if have_crypto:
             tub = Tub(certFile=cert_file)
         else:
-            raise SecurityError("OpenSSL is not available, so we can't run in secure mode, aborting")
+            raise SecurityError("""
+OpenSSL/pyOpenSSL is not available, so we can't run in secure mode.
+Try running without security using 'ipcontroller -xy'.
+""")
     else:
         tub = UnauthenticatedTub()
     
     # Set the strport based on the ip and port and start listening
     if ip == '':
         strport = "tcp:%i" % port
     else:
         strport = "tcp:%i:interface=%s" % (port, ip)
     listener = tub.listenOn(strport)
     
     return tub, listener
 
 def make_client_service(controller_service, config):
     """
     Create a service that will listen for clients.
     
     This service is simply a `foolscap.Tub` instance that has a set of Referenceables
     registered with it.
     """
 
     # Now create the foolscap tub
     ip = config['controller']['client_tub']['ip']
     port = config['controller']['client_tub'].as_int('port')
     location = config['controller']['client_tub']['location']
     secure = config['controller']['client_tub']['secure']
     cert_file = config['controller']['client_tub']['cert_file']
     client_tub, client_listener = make_tub(ip, port, secure, cert_file)
     
     # Set the location in the trivial case of localhost
     if ip == 'localhost' or ip == '127.0.0.1':
         location = "127.0.0.1"
     
     if not secure:
         log.msg("WARNING: you are running the controller with no client security")
     
     def set_location_and_register():
         """Set the location for the tub and return a deferred."""
 
         def register(empty, ref, furl_file):
             client_tub.registerReference(ref, furlFile=furl_file)
         
         if location == '':
             d = client_tub.setLocationAutomatically()
         else:
             d = defer.maybeDeferred(client_tub.setLocation, "%s:%i" % (location, client_listener.getPortnum()))
             
         for ciname, ci in config['controller']['controller_interfaces'].iteritems():
             log.msg("Adapting Controller to interface: %s" % ciname)
             furl_file = ci['furl_file']
             log.msg("Saving furl for interface [%s] to file: %s" % (ciname, furl_file))
             check_furl_file_security(furl_file, secure)
             adapted_controller = import_item(ci['controller_interface'])(controller_service)
             d.addCallback(register, import_item(ci['fc_interface'])(adapted_controller), 
                 furl_file=ci['furl_file'])
     
     reactor.callWhenRunning(set_location_and_register)
     return client_tub
 
 
 def make_engine_service(controller_service, config):
     """
     Create a service that will listen for engines.
     
     This service is simply a `foolscap.Tub` instance that has a set of Referenceables
     registered with it.
     """
 
     # Now create the foolscap tub
     ip = config['controller']['engine_tub']['ip']
     port = config['controller']['engine_tub'].as_int('port')
     location = config['controller']['engine_tub']['location']
     secure = config['controller']['engine_tub']['secure']
     cert_file = config['controller']['engine_tub']['cert_file']
     engine_tub, engine_listener = make_tub(ip, port, secure, cert_file)
     
     # Set the location in the trivial case of localhost
     if ip == 'localhost' or ip == '127.0.0.1':
         location = "127.0.0.1"
     
     if not secure:
         log.msg("WARNING: you are running the controller with no engine security")
     
     def set_location_and_register():
         """Set the location for the tub and return a deferred."""
 
         def register(empty, ref, furl_file):
             engine_tub.registerReference(ref, furlFile=furl_file)
         
         if location == '':
             d = engine_tub.setLocationAutomatically()
         else:
             d = defer.maybeDeferred(engine_tub.setLocation, "%s:%i" % (location, engine_listener.getPortnum()))
     
         furl_file = config['controller']['engine_furl_file']
         engine_fc_interface = import_item(config['controller']['engine_fc_interface'])
         log.msg("Saving furl for the engine to file: %s" % furl_file)
         check_furl_file_security(furl_file, secure)
         fc_controller = engine_fc_interface(controller_service)
         d.addCallback(register, fc_controller, furl_file=furl_file)
     
     reactor.callWhenRunning(set_location_and_register)
     return engine_tub
     
 def start_controller():
     """
     Start the controller by creating the service hierarchy and starting the reactor.
     
     This method does the following:
     
         * It starts the controller logging
         * In execute an import statement for the controller
         * It creates 2 `foolscap.Tub` instances for the client and the engines
           and registers `foolscap.Referenceables` with the tubs to expose the
           controller to engines and clients.
     """
     config = kernel_config_manager.get_config_obj()
     
     # Start logging
     logfile = config['controller']['logfile']
     if logfile:
         logfile = logfile + str(os.getpid()) + '.log'
         try:
             openLogFile = open(logfile, 'w')
         except:
             openLogFile = sys.stdout
     else:
         openLogFile = sys.stdout
     log.startLogging(openLogFile)
     
     # Execute any user defined import statements
     cis = config['controller']['import_statement']
     if cis:
         try:
             exec cis in globals(), locals()
         except:
             log.msg("Error running import_statement: %s" % cis)
     
+    # Delete old furl files unless the reuse_furls is set
+    reuse = config['controller']['reuse_furls']
+    if not reuse:
+        paths = (config['controller']['engine_furl_file'],
+            config['controller']['controller_interfaces']['task']['furl_file'],
+            config['controller']['controller_interfaces']['multiengine']['furl_file']
+        )
+        for p in paths:
+            if os.path.isfile(p):
+                os.remove(p)
+    
     # Create the service hierarchy
     main_service = service.MultiService()
     # The controller service
     controller_service = controllerservice.ControllerService()
     controller_service.setServiceParent(main_service)
     # The client tub and all its refereceables
     client_service = make_client_service(controller_service, config)
     client_service.setServiceParent(main_service)
     # The engine tub
     engine_service = make_engine_service(controller_service, config)
     engine_service.setServiceParent(main_service)
     # Start the controller service and set things running
     main_service.startService()
     reactor.run()
 
 def init_config():
     """
     Initialize the configuration using default and command line options.
     """
     
     parser = OptionParser()
     
     # Client related options
     parser.add_option(
         "--client-ip", 
         type="string",
         dest="client_ip",
         help="the IP address or hostname the controller will listen on for client connections"
     )
     parser.add_option(
         "--client-port", 
         type="int", 
         dest="client_port",
         help="the port the controller will listen on for client connections"
     )    
     parser.add_option(
         '--client-location',
         type="string",
         dest="client_location",
         help="hostname or ip for clients to connect to"
     )
     parser.add_option(
         "-x",
         action="store_false",
         dest="client_secure",
         help="turn off all client security"
     )
     parser.add_option(
         '--client-cert-file',
         type="string",
         dest="client_cert_file",
         help="file to store the client SSL certificate"
     )
     parser.add_option(
         '--task-furl-file',
         type="string",
         dest="task_furl_file",
         help="file to store the FURL for task clients to connect with"
     )
     parser.add_option(
         '--multiengine-furl-file',
         type="string",
         dest="multiengine_furl_file",
         help="file to store the FURL for multiengine clients to connect with"
     )
     # Engine related options
     parser.add_option(
         "--engine-ip", 
         type="string",
         dest="engine_ip",
         help="the IP address or hostname the controller will listen on for engine connections"
     )
     parser.add_option(
         "--engine-port", 
         type="int", 
         dest="engine_port",
         help="the port the controller will listen on for engine connections"
     )    
     parser.add_option(
         '--engine-location',
         type="string",
         dest="engine_location",
         help="hostname or ip for engines to connect to"
     )
     parser.add_option(
         "-y",
         action="store_false",
         dest="engine_secure",
         help="turn off all engine security"
     )
     parser.add_option(
         '--engine-cert-file',
         type="string",
         dest="engine_cert_file",
         help="file to store the engine SSL certificate"
     )
     parser.add_option(
         '--engine-furl-file',
         type="string",
         dest="engine_furl_file",
         help="file to store the FURL for engines to connect with"
     )
     parser.add_option(
         "-l", "--logfile",
         type="string",
         dest="logfile",
         help="log file name (default is stdout)"
     )
     parser.add_option(
         "--ipythondir",
         type="string",
         dest="ipythondir",
         help="look for config files and profiles in this directory"
     )
+    parser.add_option(
+        "-r",
+        action="store_true",
+        dest="reuse_furls",
+        help="try to reuse all furl files"
+    )
     
     (options, args) = parser.parse_args()
     
     kernel_config_manager.update_config_obj_from_default_file(options.ipythondir)
     config = kernel_config_manager.get_config_obj()
     
     # Update with command line options
     if options.client_ip is not None:
         config['controller']['client_tub']['ip'] = options.client_ip
     if options.client_port is not None:
         config['controller']['client_tub']['port'] = options.client_port
     if options.client_location is not None:
         config['controller']['client_tub']['location'] = options.client_location
     if options.client_secure is not None:
         config['controller']['client_tub']['secure'] = options.client_secure
     if options.client_cert_file is not None:
         config['controller']['client_tub']['cert_file'] = options.client_cert_file
     if options.task_furl_file is not None:
         config['controller']['controller_interfaces']['task']['furl_file'] = options.task_furl_file
     if options.multiengine_furl_file is not None:
         config['controller']['controller_interfaces']['multiengine']['furl_file'] = options.multiengine_furl_file
     if options.engine_ip is not None:
         config['controller']['engine_tub']['ip'] = options.engine_ip
     if options.engine_port is not None:
         config['controller']['engine_tub']['port'] = options.engine_port
     if options.engine_location is not None:
         config['controller']['engine_tub']['location'] = options.engine_location
     if options.engine_secure is not None:
         config['controller']['engine_tub']['secure'] = options.engine_secure
     if options.engine_cert_file is not None:
         config['controller']['engine_tub']['cert_file'] = options.engine_cert_file
     if options.engine_furl_file is not None:
         config['controller']['engine_furl_file'] = options.engine_furl_file
+    if options.reuse_furls is not None:
+            config['controller']['reuse_furls'] = options.reuse_furls
 
     if options.logfile is not None:
         config['controller']['logfile'] = options.logfile
     
     kernel_config_manager.update_config_obj(config)
 
 def main():
     """
     After creating the configuration information, start the controller.
     """
     init_config()
     start_controller()
     
 if __name__ == "__main__":
     main()

IPython/kernel/scripts/ipengine.py

@@ -1,171 +1,176
 #!/usr/bin/env python
 # encoding: utf-8
 
 """Start the IPython Engine."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 # Python looks for an empty string at the beginning of sys.path to enable
 # importing from the cwd.
 import sys
 sys.path.insert(0, '')
 
 import sys, os
 from optparse import OptionParser
 
 from twisted.application import service
 from twisted.internet import reactor
 from twisted.python import log
 
 from IPython.kernel.fcutil import Tub, UnauthenticatedTub
 
 from IPython.kernel.core.config import config_manager as core_config_manager
 from IPython.config.cutils import import_item
 from IPython.kernel.engineservice import EngineService
 from IPython.kernel.config import config_manager as kernel_config_manager
 from IPython.kernel.engineconnector import EngineConnector
 
 
 #-------------------------------------------------------------------------------
 # Code
 #-------------------------------------------------------------------------------
 
 def start_engine():
     """
     Start the engine, by creating it and starting the Twisted reactor.
     
     This method does:
     
         * If it exists, runs the `mpi_import_statement` to call `MPI_Init`
         * Starts the engine logging
         * Creates an IPython shell and wraps it in an `EngineService`
         * Creates a `foolscap.Tub` to use in connecting to a controller.
         * Uses the tub and the `EngineService` along with a Foolscap URL
           (or FURL) to connect to the controller and register the engine
           with the controller
     """
     kernel_config = kernel_config_manager.get_config_obj()
     core_config = core_config_manager.get_config_obj()
     
 
     # Execute the mpi import statement that needs to call MPI_Init
     global mpi
     mpikey = kernel_config['mpi']['default']
     mpi_import_statement = kernel_config['mpi'].get(mpikey, None)
     if mpi_import_statement is not None:
         try:
             exec mpi_import_statement in globals()
         except:
             mpi = None
     else:
         mpi = None
     
     # Start logging
     logfile = kernel_config['engine']['logfile']
     if logfile:
         logfile = logfile + str(os.getpid()) + '.log'
         try:
             openLogFile = open(logfile, 'w')
         except:
             openLogFile = sys.stdout
     else:
         openLogFile = sys.stdout
     log.startLogging(openLogFile)
     
     # Create the underlying shell class and EngineService
     shell_class = import_item(core_config['shell']['shell_class'])
     engine_service = EngineService(shell_class, mpi=mpi)
     shell_import_statement = core_config['shell']['import_statement']
     if shell_import_statement:
         try:
             engine_service.execute(shell_import_statement)
         except:
-            log.msg("Error running import_statement: %s" % sis)
+            log.msg("Error running import_statement: %s" % shell_import_statement)
     
     # Create the service hierarchy
     main_service = service.MultiService()
     engine_service.setServiceParent(main_service)
     tub_service = Tub()
     tub_service.setServiceParent(main_service)
     # This needs to be called before the connection is initiated
     main_service.startService()
     
     # This initiates the connection to the controller and calls
     # register_engine to tell the controller we are ready to do work
     engine_connector = EngineConnector(tub_service)
     furl_file = kernel_config['engine']['furl_file']
+    log.msg("Using furl file: %s" % furl_file)
     d = engine_connector.connect_to_controller(engine_service, furl_file)
-    d.addErrback(lambda _: reactor.stop())
+    def handle_error(f):
+        log.err(f)
+        if reactor.running:
+            reactor.stop()
+    d.addErrback(handle_error)
     
     reactor.run()
 
 
 def init_config():
     """
     Initialize the configuration using default and command line options.
     """
     
     parser = OptionParser()
     
     parser.add_option(
         "--furl-file",
         type="string", 
         dest="furl_file",
         help="The filename containing the FURL of the controller"
     )
     parser.add_option(
         "--mpi",
         type="string",
         dest="mpi",
         help="How to enable MPI (mpi4py, pytrilinos, or empty string to disable)"
     )
     parser.add_option(
         "-l",
         "--logfile",
         type="string",
         dest="logfile",
         help="log file name (default is stdout)"
     )
     parser.add_option(
         "--ipythondir",
         type="string",
         dest="ipythondir",
         help="look for config files and profiles in this directory"
     )
     
     (options, args) = parser.parse_args()
     
     kernel_config_manager.update_config_obj_from_default_file(options.ipythondir)
     core_config_manager.update_config_obj_from_default_file(options.ipythondir)
     
     kernel_config = kernel_config_manager.get_config_obj()
     # Now override with command line options
     if options.furl_file is not None:
         kernel_config['engine']['furl_file'] = options.furl_file
     if options.logfile is not None:
         kernel_config['engine']['logfile'] = options.logfile
     if options.mpi is not None:
         kernel_config['mpi']['default'] = options.mpi
 
 
 def main():
     """
     After creating the configuration information, start the engine.
     """
     init_config()
     start_engine()
 
 
 if __name__ == "__main__":
-    main()
  No newline at end of file
+    main()

IPython/kernel/tests/engineservicetest.py

@@ -1,373 +1,373
 # encoding: utf-8
 
 """Test template for complete engine object"""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 cPickle as pickle
 
 from twisted.internet import defer, reactor
 from twisted.python import failure
 from twisted.application import service
 import zope.interface as zi
 
 from IPython.kernel import newserialized
 from IPython.kernel import error
 from IPython.kernel.pickleutil import can, uncan
 import IPython.kernel.engineservice as es
 from IPython.kernel.core.interpreter import Interpreter
 from IPython.testing.parametric import Parametric, parametric
 
 #-------------------------------------------------------------------------------
 # Tests
 #-------------------------------------------------------------------------------
 
     
 # A sequence of valid commands run through execute
 validCommands = ['a=5',
                  'b=10',
                  'a=5; b=10; c=a+b',
                  'import math; 2.0*math.pi',
                  """def f():
     result = 0.0
     for i in range(10):
         result += i
 """,
                  'if 1<2: a=5',
                  """import time
 time.sleep(0.1)""",
                 """from math import cos;
 x = 1.0*cos(0.5)""", # Semicolons lead to Discard ast nodes that should be discarded
                 """from sets import Set
 s = Set()
    """, # Trailing whitespace should be allowed.
                 """import math
 math.cos(1.0)""", # Test a method call with a discarded return value
                 """x=1.0234
 a=5; b=10""", # Test an embedded semicolon
                 """x=1.0234
 a=5; b=10;""" # Test both an embedded and trailing semicolon
                  ]
                  
 # A sequence of commands that raise various exceptions
 invalidCommands = [('a=1/0',ZeroDivisionError),
                    ('print v',NameError),
                    ('l=[];l[0]',IndexError),
                    ("d={};d['a']",KeyError),
                    ("assert 1==0",AssertionError),
                    ("import abababsdbfsbaljasdlja",ImportError),
                    ("raise Exception()",Exception)]
 
 def testf(x):
     return 2.0*x
 
 globala = 99
 
 def testg(x):
     return  globala*x
 
 class IEngineCoreTestCase(object):
     """Test an IEngineCore implementer."""
 
     def createShell(self):
         return Interpreter()
 
     def catchQueueCleared(self, f):
         try:
             f.raiseException()
         except error.QueueCleared:
             pass
         
     def testIEngineCoreInterface(self):
         """Does self.engine claim to implement IEngineCore?"""
         self.assert_(es.IEngineCore.providedBy(self.engine))
         
     def testIEngineCoreInterfaceMethods(self):
         """Does self.engine have the methods and attributes in IEngineCore."""
         for m in list(es.IEngineCore):
             self.assert_(hasattr(self.engine, m))
     
     def testIEngineCoreDeferreds(self):
         d = self.engine.execute('a=5')
         d.addCallback(lambda _: self.engine.pull('a'))
         d.addCallback(lambda _: self.engine.get_result())
         d.addCallback(lambda _: self.engine.keys())
         d.addCallback(lambda _: self.engine.push(dict(a=10)))
         return d
     
     def runTestExecute(self, cmd):
         self.shell = Interpreter()
         actual = self.shell.execute(cmd)
         def compare(computed):
             actual['id'] = computed['id']
             self.assertEquals(actual, computed)
         d = self.engine.execute(cmd)
         d.addCallback(compare)
         return d
     
     @parametric
     def testExecute(cls):
         return [(cls.runTestExecute, cmd) for cmd in validCommands]
 
     def runTestExecuteFailures(self, cmd, exc):
         def compare(f):
             self.assertRaises(exc, f.raiseException)
         d = self.engine.execute(cmd)
         d.addErrback(compare)
         return d
     
     @parametric
     def testExecuteFailuresEngineService(cls):
         return [(cls.runTestExecuteFailures, cmd, exc)
                 for cmd, exc in invalidCommands]
     
     def runTestPushPull(self, o):
         d = self.engine.push(dict(a=o))
         d.addCallback(lambda r: self.engine.pull('a'))
         d.addCallback(lambda r: self.assertEquals(o,r))
         return d
     
     @parametric
     def testPushPull(cls):
         objs = [10,"hi there",1.2342354,{"p":(1,2)},None]
         return [(cls.runTestPushPull, o) for o in objs]
         
     def testPullNameError(self):
         d = self.engine.push(dict(a=5))
         d.addCallback(lambda _:self.engine.reset())
         d.addCallback(lambda _: self.engine.pull("a"))
         d.addErrback(lambda f: self.assertRaises(NameError, f.raiseException))
         return d        
     
     def testPushPullFailures(self):
         d = self.engine.pull('a')
         d.addErrback(lambda f: self.assertRaises(NameError, f.raiseException))
         d.addCallback(lambda _: self.engine.execute('l = lambda x: x'))
         d.addCallback(lambda _: self.engine.pull('l'))
         d.addErrback(lambda f: self.assertRaises(pickle.PicklingError, f.raiseException))
         d.addCallback(lambda _: self.engine.push(dict(l=lambda x: x)))
         d.addErrback(lambda f: self.assertRaises(pickle.PicklingError, f.raiseException))
         return d
         
     def testPushPullArray(self):
         try:
             import numpy
         except:
             return
         a = numpy.random.random(1000)
         d = self.engine.push(dict(a=a))
         d.addCallback(lambda _: self.engine.pull('a'))
         d.addCallback(lambda b: b==a)
         d.addCallback(lambda c: c.all())
         return self.assertDeferredEquals(d, True)
         
     def testPushFunction(self):
                     
         d = self.engine.push_function(dict(f=testf))
         d.addCallback(lambda _: self.engine.execute('result = f(10)'))
         d.addCallback(lambda _: self.engine.pull('result'))
         d.addCallback(lambda r: self.assertEquals(r, testf(10)))
         return d
 
     def testPullFunction(self):
         d = self.engine.push_function(dict(f=testf, g=testg))
         d.addCallback(lambda _: self.engine.pull_function(('f','g')))
         d.addCallback(lambda r: self.assertEquals(r[0](10), testf(10)))
         return d
         
     def testPushFunctionGlobal(self):
         """Make sure that pushed functions pick up the user's namespace for globals."""
         d = self.engine.push(dict(globala=globala))
         d.addCallback(lambda _: self.engine.push_function(dict(g=testg)))
         d.addCallback(lambda _: self.engine.execute('result = g(10)'))
         d.addCallback(lambda _: self.engine.pull('result'))
         d.addCallback(lambda r: self.assertEquals(r, testg(10)))
         return d
         
     def testGetResultFailure(self):
         d = self.engine.get_result(None)
         d.addErrback(lambda f: self.assertRaises(IndexError, f.raiseException))
         d.addCallback(lambda _: self.engine.get_result(10))
         d.addErrback(lambda f: self.assertRaises(IndexError, f.raiseException))
         return d
 
     def runTestGetResult(self, cmd):
         self.shell = Interpreter()
         actual = self.shell.execute(cmd)
         def compare(computed):
             actual['id'] = computed['id']
             self.assertEquals(actual, computed)
         d = self.engine.execute(cmd)
         d.addCallback(lambda r: self.engine.get_result(r['number']))
         d.addCallback(compare)
         return d
     
     @parametric
     def testGetResult(cls):
         return [(cls.runTestGetResult, cmd) for cmd in validCommands]
     
     def testGetResultDefault(self):
         cmd = 'a=5'
         shell = self.createShell()
         shellResult = shell.execute(cmd)
         def popit(dikt, key):
             dikt.pop(key)
             return dikt
         d = self.engine.execute(cmd)
         d.addCallback(lambda _: self.engine.get_result())
         d.addCallback(lambda r: self.assertEquals(shellResult, popit(r,'id')))
         return d
 
     def testKeys(self):
         d = self.engine.keys()
         d.addCallback(lambda s: isinstance(s, list))
         d.addCallback(lambda r: self.assertEquals(r, True))
         return d
             
 Parametric(IEngineCoreTestCase)
             
 class IEngineSerializedTestCase(object):
     """Test an IEngineCore implementer."""
         
     def testIEngineSerializedInterface(self):
         """Does self.engine claim to implement IEngineCore?"""
         self.assert_(es.IEngineSerialized.providedBy(self.engine))
         
     def testIEngineSerializedInterfaceMethods(self):
-        """Does self.engine have the methods and attributes in IEngireCore."""
+        """Does self.engine have the methods and attributes in IEngineCore."""
         for m in list(es.IEngineSerialized):
             self.assert_(hasattr(self.engine, m))
        
     def testIEngineSerializedDeferreds(self):
         dList = []
         d = self.engine.push_serialized(dict(key=newserialized.serialize(12345)))
         self.assert_(isinstance(d, defer.Deferred))
         dList.append(d)
         d = self.engine.pull_serialized('key')
         self.assert_(isinstance(d, defer.Deferred))
         dList.append(d)
         D = defer.DeferredList(dList)
         return D
                 
     def testPushPullSerialized(self):
         objs = [10,"hi there",1.2342354,{"p":(1,2)}]
         d = defer.succeed(None)
         for o in objs:
             self.engine.push_serialized(dict(key=newserialized.serialize(o)))
             value = self.engine.pull_serialized('key')
             value.addCallback(lambda serial: newserialized.IUnSerialized(serial).getObject())
             d = self.assertDeferredEquals(value,o,d)
         return d
 
     def testPullSerializedFailures(self):
         d = self.engine.pull_serialized('a')
         d.addErrback(lambda f: self.assertRaises(NameError, f.raiseException))
         d.addCallback(lambda _: self.engine.execute('l = lambda x: x'))
         d.addCallback(lambda _: self.engine.pull_serialized('l'))
         d.addErrback(lambda f: self.assertRaises(pickle.PicklingError, f.raiseException))
         return d
 
 Parametric(IEngineSerializedTestCase)
 
 class IEngineQueuedTestCase(object):
     """Test an IEngineQueued implementer."""
         
     def testIEngineQueuedInterface(self):
         """Does self.engine claim to implement IEngineQueued?"""
         self.assert_(es.IEngineQueued.providedBy(self.engine))
         
     def testIEngineQueuedInterfaceMethods(self):
-        """Does self.engine have the methods and attributes in IEngireQueued."""
+        """Does self.engine have the methods and attributes in IEngineQueued."""
         for m in list(es.IEngineQueued):
             self.assert_(hasattr(self.engine, m))
             
     def testIEngineQueuedDeferreds(self): 
         dList = []
         d = self.engine.clear_queue()
         self.assert_(isinstance(d, defer.Deferred))
         dList.append(d)
         d = self.engine.queue_status()
         self.assert_(isinstance(d, defer.Deferred))
         dList.append(d)
         D = defer.DeferredList(dList)
         return D
             
     def testClearQueue(self):
         result = self.engine.clear_queue()
         d1 = self.assertDeferredEquals(result, None)
         d1.addCallback(lambda _: self.engine.queue_status())
         d2 = self.assertDeferredEquals(d1, {'queue':[], 'pending':'None'})
         return d2
         
     def testQueueStatus(self):
         result = self.engine.queue_status()
         result.addCallback(lambda r: 'queue' in r and 'pending' in r)
         d = self.assertDeferredEquals(result, True)
         return d
 
 Parametric(IEngineQueuedTestCase)
 
 class IEnginePropertiesTestCase(object):
     """Test an IEngineProperties implementor."""
     
     def testIEnginePropertiesInterface(self):
         """Does self.engine claim to implement IEngineProperties?"""
         self.assert_(es.IEngineProperties.providedBy(self.engine))
     
     def testIEnginePropertiesInterfaceMethods(self):
-        """Does self.engine have the methods and attributes in IEngireProperties."""
+        """Does self.engine have the methods and attributes in IEngineProperties."""
         for m in list(es.IEngineProperties):
             self.assert_(hasattr(self.engine, m))
     
     def testGetSetProperties(self):
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d = self.engine.set_properties(dikt)
         d.addCallback(lambda r: self.engine.get_properties())
         d = self.assertDeferredEquals(d, dikt)
         d.addCallback(lambda r: self.engine.get_properties(('c',)))
         d = self.assertDeferredEquals(d, {'c': dikt['c']})
         d.addCallback(lambda r: self.engine.set_properties(dict(c=False)))
         d.addCallback(lambda r: self.engine.get_properties(('c', 'd')))
         d = self.assertDeferredEquals(d, dict(c=False, d=None))
         return d
     
     def testClearProperties(self):
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d = self.engine.set_properties(dikt)
         d.addCallback(lambda r: self.engine.clear_properties())
         d.addCallback(lambda r: self.engine.get_properties())
         d = self.assertDeferredEquals(d, {})
         return d
     
     def testDelHasProperties(self):
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d = self.engine.set_properties(dikt)
         d.addCallback(lambda r: self.engine.del_properties(('b','e')))
         d.addCallback(lambda r: self.engine.has_properties(('a','b','c','d','e')))
         d = self.assertDeferredEquals(d, [True, False, True, True, False])
         return d
     
     def testStrictDict(self):
         s = """from IPython.kernel.engineservice import get_engine
 p = get_engine(%s).properties"""%self.engine.id
         d = self.engine.execute(s)
         d.addCallback(lambda r: self.engine.execute("p['a'] = lambda _:None"))
         d = self.assertDeferredRaises(d, error.InvalidProperty)
         d.addCallback(lambda r: self.engine.execute("p['a'] = range(5)"))
         d.addCallback(lambda r: self.engine.execute("p['a'].append(5)"))
         d.addCallback(lambda r: self.engine.get_properties('a'))
         d = self.assertDeferredEquals(d, dict(a=range(5)))
         return d
         
 Parametric(IEnginePropertiesTestCase)

IPython/kernel/tests/multienginetest.py

@@ -1,828 +1,827
 # encoding: utf-8
 
 """"""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Imports
 #-------------------------------------------------------------------------------
 
 from twisted.internet import defer
 
 from IPython.kernel import engineservice as es
 from IPython.kernel import multiengine as me
 from IPython.kernel import newserialized
-from IPython.kernel.error import NotDefined
 from IPython.testing import util
 from IPython.testing.parametric import parametric, Parametric
 from IPython.kernel import newserialized
 from IPython.kernel.util import printer
 from IPython.kernel.error import (InvalidEngineID,
     NoEnginesRegistered,
     CompositeError,
     InvalidDeferredID)
 from IPython.kernel.tests.engineservicetest import validCommands, invalidCommands
 from IPython.kernel.core.interpreter import Interpreter
 
 
 #-------------------------------------------------------------------------------
 # Base classes and utilities
 #-------------------------------------------------------------------------------
 
 class IMultiEngineBaseTestCase(object):
     """Basic utilities for working with multiengine tests.
 
     Some subclass should define:
 
     * self.multiengine
     * self.engines to keep track of engines for clean up"""
 
     def createShell(self):
         return Interpreter()
 
     def addEngine(self, n=1):
         for i in range(n):
             e = es.EngineService()
             e.startService()
             regDict = self.controller.register_engine(es.QueuedEngine(e), None)
             e.id = regDict['id']
             self.engines.append(e)
 
 
 def testf(x):
     return 2.0*x
 
 
 globala = 99
 
 
 def testg(x):
     return  globala*x
 
 
 def isdid(did):
     if not isinstance(did, str):
         return False
     if not len(did)==40:
         return False
     return True
 
 
 def _raise_it(f):
     try:
         f.raiseException()
     except CompositeError, e:
         e.raise_exception()
 
 #-------------------------------------------------------------------------------
 # IMultiEngineTestCase
 #-------------------------------------------------------------------------------
 
 class IMultiEngineTestCase(IMultiEngineBaseTestCase):
     """A test for any object that implements IEngineMultiplexer.
 
     self.multiengine must be defined and implement IEngineMultiplexer.
     """
 
     def testIMultiEngineInterface(self):
         """Does self.engine claim to implement IEngineCore?"""
         self.assert_(me.IEngineMultiplexer.providedBy(self.multiengine))
         self.assert_(me.IMultiEngine.providedBy(self.multiengine))
 
     def testIEngineMultiplexerInterfaceMethods(self):
         """Does self.engine have the methods and attributes in IEngineCore."""
         for m in list(me.IEngineMultiplexer):
             self.assert_(hasattr(self.multiengine, m))
 
     def testIEngineMultiplexerDeferreds(self):
         self.addEngine(1)
         d= self.multiengine.execute('a=5', targets=0)
         d.addCallback(lambda _: self.multiengine.push(dict(a=5),targets=0))
         d.addCallback(lambda _: self.multiengine.push(dict(a=5, b='asdf', c=[1,2,3]),targets=0))
         d.addCallback(lambda _: self.multiengine.pull(('a','b','c'),targets=0))
         d.addCallback(lambda _: self.multiengine.get_result(targets=0))
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.keys(targets=0))
         d.addCallback(lambda _: self.multiengine.push_serialized(dict(a=newserialized.serialize(10)),targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a',targets=0))
         d.addCallback(lambda _: self.multiengine.clear_queue(targets=0))
         d.addCallback(lambda _: self.multiengine.queue_status(targets=0))
         return d
 
     def testInvalidEngineID(self):
          self.addEngine(1)
          badID = 100
          d = self.multiengine.execute('a=5', targets=badID)
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.push(dict(a=5), targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.pull('a', targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.reset(targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.keys(targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.push_serialized(dict(a=newserialized.serialize(10)), targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          d.addCallback(lambda _: self.multiengine.queue_status(targets=badID))
          d.addErrback(lambda f: self.assertRaises(InvalidEngineID, f.raiseException))
          return d
 
     def testNoEnginesRegistered(self):
         badID = 'all'
         d= self.multiengine.execute('a=5', targets=badID)
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.push(dict(a=5), targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.pull('a', targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.get_result(targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.reset(targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.keys(targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.push_serialized(dict(a=newserialized.serialize(10)), targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         d.addCallback(lambda _: self.multiengine.queue_status(targets=badID))
         d.addErrback(lambda f: self.assertRaises(NoEnginesRegistered, f.raiseException))
         return d
 
     def runExecuteAll(self, d, cmd, shell):
         actual = shell.execute(cmd)
         d.addCallback(lambda _: self.multiengine.execute(cmd))
         def compare(result):
             for r in result:
                 actual['id'] = r['id']
                 self.assertEquals(r, actual)
         d.addCallback(compare)
 
     def testExecuteAll(self):
         self.addEngine(4)
         d= defer.Deferred()
         shell = Interpreter()
         for cmd in validCommands:
                 self.runExecuteAll(d, cmd, shell)
         d.callback(None)
         return d
 
     # The following two methods show how to do parametrized
     # tests.  This is really slick!  Same is used above.
     def runExecuteFailures(self, cmd, exc):
         self.addEngine(4)
         d= self.multiengine.execute(cmd)
         d.addErrback(lambda f: self.assertRaises(exc, _raise_it, f))
         return d
 
     @parametric
     def testExecuteFailuresMultiEng(cls):
         return [(cls.runExecuteFailures,cmd,exc) for
                 cmd,exc in invalidCommands]
 
     def testPushPull(self):
         self.addEngine(1)
         objs = [10,"hi there",1.2342354,{"p":(1,2)}]
         d= self.multiengine.push(dict(key=objs[0]), targets=0)
         d.addCallback(lambda _: self.multiengine.pull('key', targets=0))
         d.addCallback(lambda r: self.assertEquals(r, [objs[0]]))
         d.addCallback(lambda _: self.multiengine.push(dict(key=objs[1]), targets=0))
         d.addCallback(lambda _: self.multiengine.pull('key', targets=0))
         d.addCallback(lambda r: self.assertEquals(r, [objs[1]]))
         d.addCallback(lambda _: self.multiengine.push(dict(key=objs[2]), targets=0))
         d.addCallback(lambda _: self.multiengine.pull('key', targets=0))
         d.addCallback(lambda r: self.assertEquals(r, [objs[2]]))
         d.addCallback(lambda _: self.multiengine.push(dict(key=objs[3]), targets=0))
         d.addCallback(lambda _: self.multiengine.pull('key', targets=0))
         d.addCallback(lambda r: self.assertEquals(r, [objs[3]]))
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.pull('a', targets=0))
         d.addErrback(lambda f: self.assertRaises(NameError, _raise_it, f))
         d.addCallback(lambda _: self.multiengine.push(dict(a=10,b=20)))
         d.addCallback(lambda _: self.multiengine.pull(('a','b')))
         d.addCallback(lambda r: self.assertEquals(r, [[10,20]]))
         return d
 
     def testPushPullAll(self):
         self.addEngine(4)
         d= self.multiengine.push(dict(a=10))
         d.addCallback(lambda _: self.multiengine.pull('a'))
         d.addCallback(lambda r: self.assert_(r==[10,10,10,10]))
         d.addCallback(lambda _: self.multiengine.push(dict(a=10, b=20)))
         d.addCallback(lambda _: self.multiengine.pull(('a','b')))
         d.addCallback(lambda r: self.assert_(r==4*[[10,20]]))
         d.addCallback(lambda _: self.multiengine.push(dict(a=10, b=20), targets=0))
         d.addCallback(lambda _: self.multiengine.pull(('a','b'), targets=0))
         d.addCallback(lambda r: self.assert_(r==[[10,20]]))
         d.addCallback(lambda _: self.multiengine.push(dict(a=None, b=None), targets=0))
         d.addCallback(lambda _: self.multiengine.pull(('a','b'), targets=0))
         d.addCallback(lambda r: self.assert_(r==[[None,None]]))
         return d
 
     def testPushPullSerialized(self):
         self.addEngine(1)
         objs = [10,"hi there",1.2342354,{"p":(1,2)}]
         d= self.multiengine.push_serialized(dict(key=newserialized.serialize(objs[0])), targets=0)
         d.addCallback(lambda _: self.multiengine.pull_serialized('key', targets=0))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, objs[0]))
         d.addCallback(lambda _: self.multiengine.push_serialized(dict(key=newserialized.serialize(objs[1])), targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('key', targets=0))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, objs[1]))
         d.addCallback(lambda _: self.multiengine.push_serialized(dict(key=newserialized.serialize(objs[2])), targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('key', targets=0))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, objs[2]))
         d.addCallback(lambda _: self.multiengine.push_serialized(dict(key=newserialized.serialize(objs[3])), targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('key', targets=0))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, objs[3]))
         d.addCallback(lambda _: self.multiengine.push(dict(a=10,b=range(5)), targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized(('a','b'), targets=0))
         d.addCallback(lambda serial: [newserialized.IUnSerialized(s).getObject() for s in serial[0]])
         d.addCallback(lambda r: self.assertEquals(r, [10, range(5)]))
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=0))
         d.addErrback(lambda f: self.assertRaises(NameError, _raise_it, f))
         return d
 
         objs = [10,"hi there",1.2342354,{"p":(1,2)}]
         d= defer.succeed(None)
         for o in objs:
             self.multiengine.push_serialized(0, key=newserialized.serialize(o))
             value = self.multiengine.pull_serialized(0, 'key')
             value.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
             d = self.assertDeferredEquals(value,o,d)
         return d
 
     def runGetResultAll(self, d, cmd, shell):
         actual = shell.execute(cmd)
         d.addCallback(lambda _: self.multiengine.execute(cmd))
         d.addCallback(lambda _: self.multiengine.get_result())
         def compare(result):
             for r in result:
                 actual['id'] = r['id']
                 self.assertEquals(r, actual)
         d.addCallback(compare)
 
     def testGetResultAll(self):
         self.addEngine(4)
         d= defer.Deferred()
         shell = Interpreter()
         for cmd in validCommands:
                 self.runGetResultAll(d, cmd, shell)
         d.callback(None)
         return d
 
     def testGetResultDefault(self):
         self.addEngine(1)
         target = 0
         cmd = 'a=5'
         shell = self.createShell()
         shellResult = shell.execute(cmd)
         def popit(dikt, key):
             dikt.pop(key)
             return dikt
         d= self.multiengine.execute(cmd, targets=target)
         d.addCallback(lambda _: self.multiengine.get_result(targets=target))
         d.addCallback(lambda r: self.assertEquals(shellResult, popit(r[0],'id')))
         return d
 
     def testGetResultFailure(self):
         self.addEngine(1)
         d= self.multiengine.get_result(None, targets=0)
         d.addErrback(lambda f: self.assertRaises(IndexError, _raise_it, f))
         d.addCallback(lambda _: self.multiengine.get_result(10, targets=0))
         d.addErrback(lambda f: self.assertRaises(IndexError, _raise_it, f))
         return d
 
     def testPushFunction(self):
         self.addEngine(1)
         d= self.multiengine.push_function(dict(f=testf), targets=0)
         d.addCallback(lambda _: self.multiengine.execute('result = f(10)', targets=0))
         d.addCallback(lambda _: self.multiengine.pull('result', targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0], testf(10)))
         d.addCallback(lambda _: self.multiengine.push(dict(globala=globala), targets=0))
         d.addCallback(lambda _: self.multiengine.push_function(dict(g=testg), targets=0))
         d.addCallback(lambda _: self.multiengine.execute('result = g(10)', targets=0))
         d.addCallback(lambda _: self.multiengine.pull('result', targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0], testg(10)))
         return d
 
     def testPullFunction(self):
         self.addEngine(1)
         d= self.multiengine.push(dict(a=globala), targets=0)
         d.addCallback(lambda _: self.multiengine.push_function(dict(f=testf), targets=0))
         d.addCallback(lambda _: self.multiengine.pull_function('f', targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0](10), testf(10)))
         d.addCallback(lambda _: self.multiengine.execute("def g(x): return x*x", targets=0))
         d.addCallback(lambda _: self.multiengine.pull_function(('f','g'),targets=0))
         d.addCallback(lambda r: self.assertEquals((r[0][0](10),r[0][1](10)), (testf(10), 100)))
         return d
 
     def testPushFunctionAll(self):
         self.addEngine(4)
         d= self.multiengine.push_function(dict(f=testf))
         d.addCallback(lambda _: self.multiengine.execute('result = f(10)'))
         d.addCallback(lambda _: self.multiengine.pull('result'))
         d.addCallback(lambda r: self.assertEquals(r, 4*[testf(10)]))
         d.addCallback(lambda _: self.multiengine.push(dict(globala=globala)))
         d.addCallback(lambda _: self.multiengine.push_function(dict(testg=testg)))
         d.addCallback(lambda _: self.multiengine.execute('result = testg(10)'))
         d.addCallback(lambda _: self.multiengine.pull('result'))
         d.addCallback(lambda r: self.assertEquals(r, 4*[testg(10)]))
         return d
 
     def testPullFunctionAll(self):
         self.addEngine(4)
         d= self.multiengine.push_function(dict(f=testf))
         d.addCallback(lambda _: self.multiengine.pull_function('f'))
         d.addCallback(lambda r: self.assertEquals([func(10) for func in r], 4*[testf(10)]))
         return d
 
     def testGetIDs(self):
         self.addEngine(1)
         d= self.multiengine.get_ids()
         d.addCallback(lambda r: self.assertEquals(r, [0]))
         d.addCallback(lambda _: self.addEngine(3))
         d.addCallback(lambda _: self.multiengine.get_ids())
         d.addCallback(lambda r: self.assertEquals(r, [0,1,2,3]))
         return d
 
     def testClearQueue(self):
         self.addEngine(4)
         d= self.multiengine.clear_queue()
         d.addCallback(lambda r: self.assertEquals(r,4*[None]))
         return d
 
     def testQueueStatus(self):
         self.addEngine(4)
         d= self.multiengine.queue_status(targets=0)
         d.addCallback(lambda r: self.assert_(isinstance(r[0],tuple)))
         return d
 
     def testGetSetProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.get_properties())
         d.addCallback(lambda r: self.assertEquals(r, 4*[dikt]))
         d.addCallback(lambda r: self.multiengine.get_properties(('c',)))
         d.addCallback(lambda r: self.assertEquals(r, 4*[{'c': dikt['c']}]))
         d.addCallback(lambda r: self.multiengine.set_properties(dict(c=False)))
         d.addCallback(lambda r: self.multiengine.get_properties(('c', 'd')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[dict(c=False, d=None)]))
         return d
 
     def testClearProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.clear_properties())
         d.addCallback(lambda r: self.multiengine.get_properties())
         d.addCallback(lambda r: self.assertEquals(r, 4*[{}]))
         return d
 
     def testDelHasProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.del_properties(('b','e')))
         d.addCallback(lambda r: self.multiengine.has_properties(('a','b','c','d','e')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[True, False, True, True, False]]))
         return d
 
 Parametric(IMultiEngineTestCase)
 
 #-------------------------------------------------------------------------------
 # ISynchronousMultiEngineTestCase
 #-------------------------------------------------------------------------------
 
 class ISynchronousMultiEngineTestCase(IMultiEngineBaseTestCase):
 
     def testISynchronousMultiEngineInterface(self):
         """Does self.engine claim to implement IEngineCore?"""
         self.assert_(me.ISynchronousEngineMultiplexer.providedBy(self.multiengine))
         self.assert_(me.ISynchronousMultiEngine.providedBy(self.multiengine))
 
     def testExecute(self):
         self.addEngine(4)
         execute = self.multiengine.execute
         d= execute('a=5', targets=0, block=True)
         d.addCallback(lambda r: self.assert_(len(r)==1))
         d.addCallback(lambda _: execute('b=10'))
         d.addCallback(lambda r: self.assert_(len(r)==4))
         d.addCallback(lambda _: execute('c=30', block=False))
         d.addCallback(lambda did: self.assert_(isdid(did)))
         d.addCallback(lambda _: execute('d=[0,1,2]', block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assert_(len(r)==4))
         return d
 
     def testPushPull(self):
         data = dict(a=10, b=1.05, c=range(10), d={'e':(1,2),'f':'hi'})
         self.addEngine(4)
         push = self.multiengine.push
         pull = self.multiengine.pull
         d= push({'data':data}, targets=0)
         d.addCallback(lambda r: pull('data', targets=0))
         d.addCallback(lambda r: self.assertEqual(r,[data]))
         d.addCallback(lambda _: push({'data':data}))
         d.addCallback(lambda r: pull('data'))
         d.addCallback(lambda r: self.assertEqual(r,4*[data]))
         d.addCallback(lambda _: push({'data':data}, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda _: pull('data', block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEqual(r,4*[data]))
         d.addCallback(lambda _: push(dict(a=10,b=20)))
         d.addCallback(lambda _: pull(('a','b')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[10,20]]))
         return d
 
     def testPushPullFunction(self):
         self.addEngine(4)
         pushf = self.multiengine.push_function
         pullf = self.multiengine.pull_function
         push = self.multiengine.push
         pull = self.multiengine.pull
         execute = self.multiengine.execute
         d= pushf({'testf':testf}, targets=0)
         d.addCallback(lambda r: pullf('testf', targets=0))
         d.addCallback(lambda r: self.assertEqual(r[0](1.0), testf(1.0)))
         d.addCallback(lambda _: execute('r = testf(10)', targets=0))
         d.addCallback(lambda _: pull('r', targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0], testf(10)))
         d.addCallback(lambda _: pushf({'testf':testf}, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda _: pullf('testf', block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEqual(r[0](1.0), testf(1.0)))
         d.addCallback(lambda _: execute("def g(x): return x*x", targets=0))
         d.addCallback(lambda _: pullf(('testf','g'),targets=0))
         d.addCallback(lambda r: self.assertEquals((r[0][0](10),r[0][1](10)), (testf(10), 100)))
         return d
 
     def testGetResult(self):
         shell = Interpreter()
         result1 = shell.execute('a=10')
         result1['id'] = 0
         result2 = shell.execute('b=20')
         result2['id'] = 0
         execute= self.multiengine.execute
         get_result = self.multiengine.get_result
         self.addEngine(1)
         d= execute('a=10')
         d.addCallback(lambda _: get_result())
         d.addCallback(lambda r: self.assertEquals(r[0], result1))
         d.addCallback(lambda _: execute('b=20'))
         d.addCallback(lambda _: get_result(1))
         d.addCallback(lambda r: self.assertEquals(r[0], result1))
         d.addCallback(lambda _: get_result(2, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r[0], result2))
         return d
 
     def testResetAndKeys(self):
         self.addEngine(1)
 
         #Blocking mode
         d= self.multiengine.push(dict(a=10, b=20, c=range(10)), targets=0)
         d.addCallback(lambda _: self.multiengine.keys(targets=0))
         def keys_found(keys):
             self.assert_('a' in keys[0])
             self.assert_('b' in keys[0])
             self.assert_('b' in keys[0])
         d.addCallback(keys_found)
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.keys(targets=0))
         def keys_not_found(keys):
             self.assert_('a' not in keys[0])
             self.assert_('b' not in keys[0])
             self.assert_('b' not in keys[0])
         d.addCallback(keys_not_found)
 
         #Non-blocking mode
         d.addCallback(lambda _: self.multiengine.push(dict(a=10, b=20, c=range(10)), targets=0))
         d.addCallback(lambda _: self.multiengine.keys(targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         def keys_found(keys):
             self.assert_('a' in keys[0])
             self.assert_('b' in keys[0])
             self.assert_('b' in keys[0])
         d.addCallback(keys_found)
         d.addCallback(lambda _: self.multiengine.reset(targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda _: self.multiengine.keys(targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         def keys_not_found(keys):
             self.assert_('a' not in keys[0])
             self.assert_('b' not in keys[0])
             self.assert_('b' not in keys[0])
         d.addCallback(keys_not_found)
 
         return d
 
     def testPushPullSerialized(self):
         self.addEngine(1)
         dikt = dict(a=10,b='hi there',c=1.2345,d={'p':(1,2)})
         sdikt = {}
         for k,v in dikt.iteritems():
             sdikt[k] = newserialized.serialize(v)
         d= self.multiengine.push_serialized(dict(a=sdikt['a']), targets=0)
         d.addCallback(lambda _: self.multiengine.pull('a',targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0], dikt['a']))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=0))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, dikt['a']))
         d.addCallback(lambda _: self.multiengine.push_serialized(sdikt, targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized(sdikt.keys(), targets=0))
         d.addCallback(lambda serial: [newserialized.IUnSerialized(s).getObject() for s in serial[0]])
         d.addCallback(lambda r: self.assertEquals(r, dikt.values()))
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=0))
         d.addErrback(lambda f: self.assertRaises(NameError, _raise_it, f))
 
         #Non-blocking mode
         d.addCallback(lambda r: self.multiengine.push_serialized(dict(a=sdikt['a']), targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda _: self.multiengine.pull('a',targets=0))
         d.addCallback(lambda r: self.assertEquals(r[0], dikt['a']))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda serial: newserialized.IUnSerialized(serial[0]).getObject())
         d.addCallback(lambda r: self.assertEquals(r, dikt['a']))
         d.addCallback(lambda _: self.multiengine.push_serialized(sdikt, targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda _: self.multiengine.pull_serialized(sdikt.keys(), targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda serial: [newserialized.IUnSerialized(s).getObject() for s in serial[0]])
         d.addCallback(lambda r: self.assertEquals(r, dikt.values()))
         d.addCallback(lambda _: self.multiengine.reset(targets=0))
         d.addCallback(lambda _: self.multiengine.pull_serialized('a', targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addErrback(lambda f: self.assertRaises(NameError, _raise_it, f))
         return d
 
     def testClearQueue(self):
         self.addEngine(4)
         d= self.multiengine.clear_queue()
         d.addCallback(lambda r: self.multiengine.clear_queue(block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r,4*[None]))
         return d
 
     def testQueueStatus(self):
         self.addEngine(4)
         d= self.multiengine.queue_status(targets=0)
         d.addCallback(lambda r: self.assert_(isinstance(r[0],tuple)))
         d.addCallback(lambda r: self.multiengine.queue_status(targets=0, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assert_(isinstance(r[0],tuple)))
         return d
 
     def testGetIDs(self):
         self.addEngine(1)
         d= self.multiengine.get_ids()
         d.addCallback(lambda r: self.assertEquals(r, [0]))
         d.addCallback(lambda _: self.addEngine(3))
         d.addCallback(lambda _: self.multiengine.get_ids())
         d.addCallback(lambda r: self.assertEquals(r, [0,1,2,3]))
         return d
 
     def testGetSetProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.get_properties())
         d.addCallback(lambda r: self.assertEquals(r, 4*[dikt]))
         d.addCallback(lambda r: self.multiengine.get_properties(('c',)))
         d.addCallback(lambda r: self.assertEquals(r, 4*[{'c': dikt['c']}]))
         d.addCallback(lambda r: self.multiengine.set_properties(dict(c=False)))
         d.addCallback(lambda r: self.multiengine.get_properties(('c', 'd')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[dict(c=False, d=None)]))
 
         #Non-blocking
         d.addCallback(lambda r: self.multiengine.set_properties(dikt, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.get_properties(block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, 4*[dikt]))
         d.addCallback(lambda r: self.multiengine.get_properties(('c',), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, 4*[{'c': dikt['c']}]))
         d.addCallback(lambda r: self.multiengine.set_properties(dict(c=False), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.get_properties(('c', 'd'), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, 4*[dict(c=False, d=None)]))
         return d
 
     def testClearProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.clear_properties())
         d.addCallback(lambda r: self.multiengine.get_properties())
         d.addCallback(lambda r: self.assertEquals(r, 4*[{}]))
 
         #Non-blocking
         d.addCallback(lambda r: self.multiengine.set_properties(dikt, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.clear_properties(block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.get_properties(block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, 4*[{}]))
         return d
 
     def testDelHasProperties(self):
         self.addEngine(4)
         dikt = dict(a=5, b='asdf', c=True, d=None, e=range(5))
         d= self.multiengine.set_properties(dikt)
         d.addCallback(lambda r: self.multiengine.del_properties(('b','e')))
         d.addCallback(lambda r: self.multiengine.has_properties(('a','b','c','d','e')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[True, False, True, True, False]]))
 
         #Non-blocking
         d.addCallback(lambda r: self.multiengine.set_properties(dikt, block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.del_properties(('b','e'), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.has_properties(('a','b','c','d','e'), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[True, False, True, True, False]]))
         return d
 
     def test_clear_pending_deferreds(self):
         self.addEngine(4)
         did_list = []
         d= self.multiengine.execute('a=10',block=False)
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.push(dict(b=10),block=False))
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.pull(('a','b'),block=False))
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.clear_pending_deferreds())
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[0],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[1],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[2],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         return d
 
 #-------------------------------------------------------------------------------
 # Coordinator test cases
 #-------------------------------------------------------------------------------
 
 class IMultiEngineCoordinatorTestCase(object):
 
     def testScatterGather(self):
         self.addEngine(4)
         d= self.multiengine.scatter('a', range(16))
         d.addCallback(lambda r: self.multiengine.gather('a'))
         d.addCallback(lambda r: self.assertEquals(r, range(16)))
         d.addCallback(lambda _: self.multiengine.gather('asdf'))
         d.addErrback(lambda f: self.assertRaises(NameError, _raise_it, f))
         return d
 
     def testScatterGatherNumpy(self):
         try:
             import numpy
             from numpy.testing.utils import assert_array_equal, assert_array_almost_equal
         except:
             return
         else:
             self.addEngine(4)
             a = numpy.arange(16)
             d = self.multiengine.scatter('a', a)
             d.addCallback(lambda r: self.multiengine.gather('a'))
             d.addCallback(lambda r: assert_array_equal(r, a))
             return d
 
     def testMap(self):
         self.addEngine(4)
         def f(x):
             return x**2
         data = range(16)
         d= self.multiengine.map(f, data)
         d.addCallback(lambda r: self.assertEquals(r,[f(x) for x in data]))
         return d
 
 
 class ISynchronousMultiEngineCoordinatorTestCase(IMultiEngineCoordinatorTestCase):
 
     def testScatterGatherNonblocking(self):
         self.addEngine(4)
         d= self.multiengine.scatter('a', range(16), block=False)
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.gather('a', block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assertEquals(r, range(16)))
         return d
     
     def testScatterGatherNumpyNonblocking(self):
         try:
             import numpy
             from numpy.testing.utils import assert_array_equal, assert_array_almost_equal
         except:
             return
         else:
             self.addEngine(4)
             a = numpy.arange(16)
             d = self.multiengine.scatter('a', a, block=False)
             d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
             d.addCallback(lambda r: self.multiengine.gather('a', block=False))
             d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
             d.addCallback(lambda r: assert_array_equal(r, a))
             return d
     
     def test_clear_pending_deferreds(self):
         self.addEngine(4)
         did_list = []
         d= self.multiengine.scatter('a',range(16),block=False)
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.gather('a',block=False))
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.map(lambda x: x, range(16),block=False))
         d.addCallback(lambda did: did_list.append(did))
         d.addCallback(lambda _: self.multiengine.clear_pending_deferreds())
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[0],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[1],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         d.addCallback(lambda _: self.multiengine.get_pending_deferred(did_list[2],True))
         d.addErrback(lambda f: self.assertRaises(InvalidDeferredID, f.raiseException))
         return d
 
 #-------------------------------------------------------------------------------
 # Extras test cases
 #-------------------------------------------------------------------------------
 
 class IMultiEngineExtrasTestCase(object):
 
     def testZipPull(self):
         self.addEngine(4)
         d= self.multiengine.push(dict(a=10,b=20))
         d.addCallback(lambda r: self.multiengine.zip_pull(('a','b')))
         d.addCallback(lambda r: self.assert_(r, [4*[10],4*[20]]))
         return d
 
     def testRun(self):
         self.addEngine(4)
         import tempfile
         fname = tempfile.mktemp('foo.py')
         f= open(fname, 'w')
         f.write('a = 10\nb=30')
         f.close()
         d= self.multiengine.run(fname)
         d.addCallback(lambda r: self.multiengine.pull(('a','b')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[10,30]]))
         return d
 
 
 class ISynchronousMultiEngineExtrasTestCase(IMultiEngineExtrasTestCase):
 
     def testZipPullNonblocking(self):
         self.addEngine(4)
         d= self.multiengine.push(dict(a=10,b=20))
         d.addCallback(lambda r: self.multiengine.zip_pull(('a','b'), block=False))
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.assert_(r, [4*[10],4*[20]]))
         return d
 
     def testRunNonblocking(self):
         self.addEngine(4)
         import tempfile
         fname = tempfile.mktemp('foo.py')
         f= open(fname, 'w')
         f.write('a = 10\nb=30')
         f.close()
         d= self.multiengine.run(fname, block=False)
         d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
         d.addCallback(lambda r: self.multiengine.pull(('a','b')))
         d.addCallback(lambda r: self.assertEquals(r, 4*[[10,30]]))
         return d
 
 
 #-------------------------------------------------------------------------------
 # IFullSynchronousMultiEngineTestCase
 #-------------------------------------------------------------------------------
 
 class IFullSynchronousMultiEngineTestCase(ISynchronousMultiEngineTestCase,
     ISynchronousMultiEngineCoordinatorTestCase,
     ISynchronousMultiEngineExtrasTestCase):
     pass

IPython/kernel/tests/test_contexts.py

@@ -1,41 +1,43
-from __future__ import with_statement
+#from __future__ import with_statement
+
+# XXX This file is currently disabled to preserve 2.4 compatibility.
 
 #def test_simple():
 if 0:
 
     # XXX - for now, we need a running cluster to be started separately.  The
     # daemon work is almost finished, and will make much of this unnecessary.
     from IPython.kernel import client
     mec = client.MultiEngineClient(('127.0.0.1',10105))
 
     try:
         mec.get_ids()
     except ConnectionRefusedError:
         import os, time
         os.system('ipcluster -n 2 &')
         time.sleep(2)
         mec = client.MultiEngineClient(('127.0.0.1',10105))
 
     mec.block = False
 
     import itertools
     c = itertools.count()
 
     parallel = RemoteMultiEngine(mec)
 
     mec.pushAll()
 
-    with parallel as pr:
-        # A comment
-        remote()  # this means the code below only runs remotely
-        print 'Hello remote world'
-        x = range(10)
-        # Comments are OK
-        # Even misindented.
-        y = x+1
+    ## with parallel as pr:
+    ##     # A comment
+    ##     remote()  # this means the code below only runs remotely
+    ##     print 'Hello remote world'
+    ##     x = range(10)
+    ##     # Comments are OK
+    ##     # Even misindented.
+    ##     y = x+1
 
 
-    with pfor('i',sequence) as pr:
-        print x[i]
+    ## with pfor('i',sequence) as pr:
+    ##     print x[i]
 
     print pr.x + pr.y

IPython/kernel/tests/test_controllerservice.py

@@ -1,43 +1,44
 # encoding: utf-8
 
 """This file contains unittests for the kernel.engineservice.py module.
 
 Things that should be tested:
 
  - Should the EngineService return Deferred objects?
  - Run the same tests that are run in shell.py.
  - Make sure that the Interface is really implemented.
  - The startService and stopService methods.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.application.service import IService
     from IPython.kernel.controllerservice import ControllerService
     from IPython.kernel.tests import multienginetest as met
     from controllertest import IControllerCoreTestCase
     from IPython.testing.util import DeferredTestCase
 except ImportError:
-    pass
-else:
-    class BasicControllerServiceTest(DeferredTestCase,
-        IControllerCoreTestCase):
-    
-        def setUp(self):
-            self.controller  = ControllerService()
-            self.controller.startService()
-    
-        def tearDown(self):
-            self.controller.stopService()
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
+
+class BasicControllerServiceTest(DeferredTestCase,
+    IControllerCoreTestCase):
+
+    def setUp(self):
+        self.controller  = ControllerService()
+        self.controller.startService()
+
+    def tearDown(self):
+        self.controller.stopService()

IPython/kernel/tests/test_enginefc.py

@@ -1,92 +1,93
 # encoding: utf-8
 
 """This file contains unittests for the enginepb.py module."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.python import components
     from twisted.internet import reactor, defer
     from twisted.spread import pb
     from twisted.internet.base import DelayedCall
     DelayedCall.debug = True
 
     import zope.interface as zi
 
     from IPython.kernel.fcutil import Tub, UnauthenticatedTub
     from IPython.kernel import engineservice as es
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.controllerservice import IControllerBase
     from IPython.kernel.enginefc import FCRemoteEngineRefFromService, IEngineBase
     from IPython.kernel.engineservice import IEngineQueued
     from IPython.kernel.engineconnector import EngineConnector
     
     from IPython.kernel.tests.engineservicetest import \
         IEngineCoreTestCase, \
         IEngineSerializedTestCase, \
         IEngineQueuedTestCase
 except ImportError:
-    print "we got an error!!!"
-    raise
-else:
-    class EngineFCTest(DeferredTestCase, 
-                       IEngineCoreTestCase, 
-                       IEngineSerializedTestCase,
-                       IEngineQueuedTestCase
-                       ):
-        
-        zi.implements(IControllerBase)
-        
-        def setUp(self):
-        
-            # Start a server and append to self.servers
-            self.controller_reference = FCRemoteEngineRefFromService(self)
-            self.controller_tub = Tub()
-            self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
-            self.controller_tub.setLocation('127.0.0.1:10105')
-            
-            furl = self.controller_tub.registerReference(self.controller_reference)
-            self.controller_tub.startService()
-            
-            # Start an EngineService and append to services/client
-            self.engine_service = es.EngineService()
-            self.engine_service.startService()
-            self.engine_tub = Tub()
-            self.engine_tub.startService()
-            engine_connector = EngineConnector(self.engine_tub)
-            d = engine_connector.connect_to_controller(self.engine_service, furl)
-            # This deferred doesn't fire until after register_engine has returned and
-            # thus, self.engine has been defined and the tets can proceed.
-            return d
-        
-        def tearDown(self):
-            dlist = []
-            # Shut down the engine
-            d = self.engine_tub.stopService()
-            dlist.append(d)
-            # Shut down the controller
-            d = self.controller_tub.stopService()
-            dlist.append(d)
-            return defer.DeferredList(dlist)
-        
-        #---------------------------------------------------------------------------
-        # Make me look like a basic controller
-        #---------------------------------------------------------------------------
-        
-        def register_engine(self, engine_ref, id=None, ip=None, port=None, pid=None):
-            self.engine = IEngineQueued(IEngineBase(engine_ref))
-            return {'id':id}
-        
-        def unregister_engine(self, id):
-            pass
  No newline at end of file
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
+
+
+class EngineFCTest(DeferredTestCase, 
+                 IEngineCoreTestCase, 
+                 IEngineSerializedTestCase,
+                 IEngineQueuedTestCase
+                 ):
+ 
+  zi.implements(IControllerBase)
+ 
+  def setUp(self):
+ 
+      # Start a server and append to self.servers
+      self.controller_reference = FCRemoteEngineRefFromService(self)
+      self.controller_tub = Tub()
+      self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
+      self.controller_tub.setLocation('127.0.0.1:10105')
+     
+      furl = self.controller_tub.registerReference(self.controller_reference)
+      self.controller_tub.startService()
+     
+      # Start an EngineService and append to services/client
+      self.engine_service = es.EngineService()
+      self.engine_service.startService()
+      self.engine_tub = Tub()
+      self.engine_tub.startService()
+      engine_connector = EngineConnector(self.engine_tub)
+      d = engine_connector.connect_to_controller(self.engine_service, furl)
+      # This deferred doesn't fire until after register_engine has returned and
+      # thus, self.engine has been defined and the tets can proceed.
+      return d
+ 
+  def tearDown(self):
+      dlist = []
+      # Shut down the engine
+      d = self.engine_tub.stopService()
+      dlist.append(d)
+      # Shut down the controller
+      d = self.controller_tub.stopService()
+      dlist.append(d)
+      return defer.DeferredList(dlist)
+ 
+  #---------------------------------------------------------------------------
+  # Make me look like a basic controller
+  #---------------------------------------------------------------------------
+ 
+  def register_engine(self, engine_ref, id=None, ip=None, port=None, pid=None):
+      self.engine = IEngineQueued(IEngineBase(engine_ref))
+      return {'id':id}
+ 
+  def unregister_engine(self, id):
+      pass
  No newline at end of file

IPython/kernel/tests/test_engineservice.py

@@ -1,78 +1,80
 # encoding: utf-8
 
 """This file contains unittests for the kernel.engineservice.py module.
 
 Things that should be tested:
 
  - Should the EngineService return Deferred objects?
  - Run the same tests that are run in shell.py.
  - Make sure that the Interface is really implemented.
  - The startService and stopService methods.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.internet import defer
     from twisted.application.service import IService
     
     from IPython.kernel import engineservice as es
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.tests.engineservicetest import \
         IEngineCoreTestCase, \
         IEngineSerializedTestCase, \
         IEngineQueuedTestCase, \
         IEnginePropertiesTestCase
 except ImportError:
-    pass
-else:
-    class BasicEngineServiceTest(DeferredTestCase,
-                                 IEngineCoreTestCase, 
-                                 IEngineSerializedTestCase,
-                                 IEnginePropertiesTestCase):
-    
-        def setUp(self):
-            self.engine = es.EngineService()
-            self.engine.startService()
-    
-        def tearDown(self):
-            return self.engine.stopService()
-    
-    class ThreadedEngineServiceTest(DeferredTestCase,
-                                 IEngineCoreTestCase, 
-                                 IEngineSerializedTestCase,
-                                 IEnginePropertiesTestCase):
-    
-        def setUp(self):
-            self.engine = es.ThreadedEngineService()
-            self.engine.startService()
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")    
+
+
+class BasicEngineServiceTest(DeferredTestCase,
+                             IEngineCoreTestCase, 
+                             IEngineSerializedTestCase,
+                             IEnginePropertiesTestCase):
+
+    def setUp(self):
+        self.engine = es.EngineService()
+        self.engine.startService()
+
+    def tearDown(self):
+        return self.engine.stopService()
+
+class ThreadedEngineServiceTest(DeferredTestCase,
+                             IEngineCoreTestCase, 
+                             IEngineSerializedTestCase,
+                             IEnginePropertiesTestCase):
+
+    def setUp(self):
+        self.engine = es.ThreadedEngineService()
+        self.engine.startService()
+
+    def tearDown(self):
+        return self.engine.stopService()
+
+class QueuedEngineServiceTest(DeferredTestCase,
+                              IEngineCoreTestCase, 
+                              IEngineSerializedTestCase,
+                              IEnginePropertiesTestCase,
+                              IEngineQueuedTestCase):
+                          
+    def setUp(self):
+        self.rawEngine = es.EngineService()
+        self.rawEngine.startService()
+        self.engine = es.IEngineQueued(self.rawEngine)
     
-        def tearDown(self):
-            return self.engine.stopService()
-
-    class QueuedEngineServiceTest(DeferredTestCase,
-                                  IEngineCoreTestCase, 
-                                  IEngineSerializedTestCase,
-                                  IEnginePropertiesTestCase,
-                                  IEngineQueuedTestCase):
-                              
-        def setUp(self):
-            self.rawEngine = es.EngineService()
-            self.rawEngine.startService()
-            self.engine = es.IEngineQueued(self.rawEngine)
-        
-        def tearDown(self):
-            return self.rawEngine.stopService()
-
- 
+    def tearDown(self):
+        return self.rawEngine.stopService()
+
+

IPython/kernel/tests/test_multiengine.py

@@ -1,54 +1,56
 # encoding: utf-8
 
 """"""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.internet import defer
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.controllerservice import ControllerService
     from IPython.kernel import multiengine as me
     from IPython.kernel.tests.multienginetest import (IMultiEngineTestCase,
         ISynchronousMultiEngineTestCase)
 except ImportError:
-    pass
-else:    
-    class BasicMultiEngineTestCase(DeferredTestCase, IMultiEngineTestCase):
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
+
+ 
+class BasicMultiEngineTestCase(DeferredTestCase, IMultiEngineTestCase):
+
+    def setUp(self):
+        self.controller = ControllerService()
+        self.controller.startService()
+        self.multiengine = me.IMultiEngine(self.controller)
+        self.engines = []
     
-        def setUp(self):
-            self.controller = ControllerService()
-            self.controller.startService()
-            self.multiengine = me.IMultiEngine(self.controller)
-            self.engines = []
-        
-        def tearDown(self):
-            self.controller.stopService()
-            for e in self.engines:
-                e.stopService()
-
-
-    class SynchronousMultiEngineTestCase(DeferredTestCase, ISynchronousMultiEngineTestCase):
+    def tearDown(self):
+        self.controller.stopService()
+        for e in self.engines:
+            e.stopService()
+
+
+class SynchronousMultiEngineTestCase(DeferredTestCase, ISynchronousMultiEngineTestCase):
+
+    def setUp(self):
+        self.controller = ControllerService()
+        self.controller.startService()
+        self.multiengine = me.ISynchronousMultiEngine(me.IMultiEngine(self.controller))
+        self.engines = []
     
-        def setUp(self):
-            self.controller = ControllerService()
-            self.controller.startService()
-            self.multiengine = me.ISynchronousMultiEngine(me.IMultiEngine(self.controller))
-            self.engines = []
-        
-        def tearDown(self):
-            self.controller.stopService()
-            for e in self.engines:
-                e.stopService()
+    def tearDown(self):
+        self.controller.stopService()
+        for e in self.engines:
+            e.stopService()
 

IPython/kernel/tests/test_multienginefc.py

@@ -1,144 +1,144
 #!/usr/bin/env python
 # encoding: utf-8
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.internet import defer, reactor
 
     from IPython.kernel.fcutil import Tub, UnauthenticatedTub
 
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.controllerservice import ControllerService
     from IPython.kernel.multiengine import IMultiEngine
     from IPython.kernel.tests.multienginetest import IFullSynchronousMultiEngineTestCase
     from IPython.kernel.multienginefc import IFCSynchronousMultiEngine
     from IPython.kernel import multiengine as me
     from IPython.kernel.clientconnector import ClientConnector
     from IPython.kernel.parallelfunction import ParallelFunction
     from IPython.kernel.error import CompositeError
     from IPython.kernel.util import printer
 except ImportError:
-    pass
-else:
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
     
-    def _raise_it(f):
-        try:
-            f.raiseException()
-        except CompositeError, e:
-            e.raise_exception()
+def _raise_it(f):
+    try:
+        f.raiseException()
+    except CompositeError, e:
+        e.raise_exception()
+
+
+class FullSynchronousMultiEngineTestCase(DeferredTestCase, IFullSynchronousMultiEngineTestCase):
+
+    def setUp(self):
     
+        self.engines = []
+            
+        self.controller = ControllerService()
+        self.controller.startService()
+        self.imultiengine = IMultiEngine(self.controller)
+        self.mec_referenceable = IFCSynchronousMultiEngine(self.imultiengine)
+
+        self.controller_tub = Tub()
+        self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
+        self.controller_tub.setLocation('127.0.0.1:10105')
     
-    class FullSynchronousMultiEngineTestCase(DeferredTestCase, IFullSynchronousMultiEngineTestCase):
+        furl = self.controller_tub.registerReference(self.mec_referenceable)
+        self.controller_tub.startService()
     
-        def setUp(self):
-        
-            self.engines = []
-                
-            self.controller = ControllerService()
-            self.controller.startService()
-            self.imultiengine = IMultiEngine(self.controller)
-            self.mec_referenceable = IFCSynchronousMultiEngine(self.imultiengine)
-
-            self.controller_tub = Tub()
-            self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
-            self.controller_tub.setLocation('127.0.0.1:10105')
-        
-            furl = self.controller_tub.registerReference(self.mec_referenceable)
-            self.controller_tub.startService()
-        
-            self.client_tub = ClientConnector()
-            d = self.client_tub.get_multiengine_client(furl)
-            d.addCallback(self.handle_got_client)
-            return d
-        
-        def handle_got_client(self, client):
-            self.multiengine = client
+        self.client_tub = ClientConnector()
+        d = self.client_tub.get_multiengine_client(furl)
+        d.addCallback(self.handle_got_client)
+        return d
     
-        def tearDown(self):
-            dlist = []
-            # Shut down the multiengine client
-            d = self.client_tub.tub.stopService()
-            dlist.append(d)
-            # Shut down the engines
-            for e in self.engines:
-                e.stopService()
-            # Shut down the controller
-            d = self.controller_tub.stopService()
-            d.addBoth(lambda _: self.controller.stopService())
-            dlist.append(d)
-            return defer.DeferredList(dlist)
+    def handle_got_client(self, client):
+        self.multiengine = client
+
+    def tearDown(self):
+        dlist = []
+        # Shut down the multiengine client
+        d = self.client_tub.tub.stopService()
+        dlist.append(d)
+        # Shut down the engines
+        for e in self.engines:
+            e.stopService()
+        # Shut down the controller
+        d = self.controller_tub.stopService()
+        d.addBoth(lambda _: self.controller.stopService())
+        dlist.append(d)
+        return defer.DeferredList(dlist)
 
-        def test_mapper(self):
-            self.addEngine(4)
-            m = self.multiengine.mapper()
-            self.assertEquals(m.multiengine,self.multiengine)
-            self.assertEquals(m.dist,'b')
-            self.assertEquals(m.targets,'all')
-            self.assertEquals(m.block,True)
-        
-        def test_map_default(self):
-            self.addEngine(4)
-            m = self.multiengine.mapper()
-            d = m.map(lambda x: 2*x, range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            d.addCallback(lambda _: self.multiengine.map(lambda x: 2*x, range(10)))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-        
-        def test_map_noblock(self):
-            self.addEngine(4)
-            m = self.multiengine.mapper(block=False)
-            d = m.map(lambda x: 2*x, range(10))
-            d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-                
-        def test_mapper_fail(self):
-            self.addEngine(4)
-            m = self.multiengine.mapper()
-            d = m.map(lambda x: 1/0, range(10))
-            d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
-            return d
-        
-        def test_parallel(self):
-            self.addEngine(4)
-            p = self.multiengine.parallel()
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 2*x
-            d = f(range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-        
-        def test_parallel_noblock(self):
-            self.addEngine(1)
-            p = self.multiengine.parallel(block=False)
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 2*x
-            d = f(range(10))
-            d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-        
-        def test_parallel_fail(self):
-            self.addEngine(4)
-            p = self.multiengine.parallel()
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 1/0
-            d = f(range(10))
-            d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
-            return d
  No newline at end of file
+    def test_mapper(self):
+        self.addEngine(4)
+        m = self.multiengine.mapper()
+        self.assertEquals(m.multiengine,self.multiengine)
+        self.assertEquals(m.dist,'b')
+        self.assertEquals(m.targets,'all')
+        self.assertEquals(m.block,True)
+    
+    def test_map_default(self):
+        self.addEngine(4)
+        m = self.multiengine.mapper()
+        d = m.map(lambda x: 2*x, range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        d.addCallback(lambda _: self.multiengine.map(lambda x: 2*x, range(10)))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
+    
+    def test_map_noblock(self):
+        self.addEngine(4)
+        m = self.multiengine.mapper(block=False)
+        d = m.map(lambda x: 2*x, range(10))
+        d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
+            
+    def test_mapper_fail(self):
+        self.addEngine(4)
+        m = self.multiengine.mapper()
+        d = m.map(lambda x: 1/0, range(10))
+        d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
+        return d
+    
+    def test_parallel(self):
+        self.addEngine(4)
+        p = self.multiengine.parallel()
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 2*x
+        d = f(range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
+    
+    def test_parallel_noblock(self):
+        self.addEngine(1)
+        p = self.multiengine.parallel(block=False)
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 2*x
+        d = f(range(10))
+        d.addCallback(lambda did: self.multiengine.get_pending_deferred(did, True))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
+    
+    def test_parallel_fail(self):
+        self.addEngine(4)
+        p = self.multiengine.parallel()
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 1/0
+        d = f(range(10))
+        d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
+        return d
  No newline at end of file

IPython/kernel/tests/test_newserialized.py

@@ -1,102 +1,102
 # encoding: utf-8
 
 """This file contains unittests for the shell.py module."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     import zope.interface as zi
     from twisted.trial import unittest
     from IPython.testing.util import DeferredTestCase
 
     from IPython.kernel.newserialized import \
         ISerialized, \
         IUnSerialized, \
         Serialized, \
         UnSerialized, \
         SerializeIt, \
         UnSerializeIt
 except ImportError:
-    pass
-else:
-    #-------------------------------------------------------------------------------
-    # Tests
-    #-------------------------------------------------------------------------------
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
+
+#-------------------------------------------------------------------------------
+# Tests
+#-------------------------------------------------------------------------------
+
+class SerializedTestCase(unittest.TestCase):
+
+    def setUp(self):
+        pass
     
-    class SerializedTestCase(unittest.TestCase):
+    def tearDown(self):
+        pass
     
-        def setUp(self):
-            pass
-        
-        def tearDown(self):
-            pass
-        
-        def testSerializedInterfaces(self):
+    def testSerializedInterfaces(self):
 
-            us = UnSerialized({'a':10, 'b':range(10)})
-            s = ISerialized(us)
-            uss = IUnSerialized(s)
-            self.assert_(ISerialized.providedBy(s))
-            self.assert_(IUnSerialized.providedBy(us))
-            self.assert_(IUnSerialized.providedBy(uss))
-            for m in list(ISerialized):
-                self.assert_(hasattr(s, m))
-            for m in list(IUnSerialized):
-                self.assert_(hasattr(us, m))
-            for m in list(IUnSerialized):
-                self.assert_(hasattr(uss, m))
+        us = UnSerialized({'a':10, 'b':range(10)})
+        s = ISerialized(us)
+        uss = IUnSerialized(s)
+        self.assert_(ISerialized.providedBy(s))
+        self.assert_(IUnSerialized.providedBy(us))
+        self.assert_(IUnSerialized.providedBy(uss))
+        for m in list(ISerialized):
+            self.assert_(hasattr(s, m))
+        for m in list(IUnSerialized):
+            self.assert_(hasattr(us, m))
+        for m in list(IUnSerialized):
+            self.assert_(hasattr(uss, m))
 
-        def testPickleSerialized(self):
-            obj = {'a':1.45345, 'b':'asdfsdf', 'c':10000L}
-            original = UnSerialized(obj)
-            originalSer = ISerialized(original)
-            firstData = originalSer.getData()
-            firstTD = originalSer.getTypeDescriptor()
-            firstMD = originalSer.getMetadata()
-            self.assert_(firstTD == 'pickle')
-            self.assert_(firstMD == {})
-            unSerialized = IUnSerialized(originalSer)
-            secondObj = unSerialized.getObject()
-            for k, v in secondObj.iteritems():
-                self.assert_(obj[k] == v)
-            secondSer = ISerialized(UnSerialized(secondObj))
-            self.assert_(firstData == secondSer.getData())
-            self.assert_(firstTD == secondSer.getTypeDescriptor() )
-            self.assert_(firstMD == secondSer.getMetadata())
+    def testPickleSerialized(self):
+        obj = {'a':1.45345, 'b':'asdfsdf', 'c':10000L}
+        original = UnSerialized(obj)
+        originalSer = ISerialized(original)
+        firstData = originalSer.getData()
+        firstTD = originalSer.getTypeDescriptor()
+        firstMD = originalSer.getMetadata()
+        self.assert_(firstTD == 'pickle')
+        self.assert_(firstMD == {})
+        unSerialized = IUnSerialized(originalSer)
+        secondObj = unSerialized.getObject()
+        for k, v in secondObj.iteritems():
+            self.assert_(obj[k] == v)
+        secondSer = ISerialized(UnSerialized(secondObj))
+        self.assert_(firstData == secondSer.getData())
+        self.assert_(firstTD == secondSer.getTypeDescriptor() )
+        self.assert_(firstMD == secondSer.getMetadata())
+    
+    def testNDArraySerialized(self):
+        try:
+            import numpy
+        except ImportError:
+            pass
+        else:
+            a = numpy.linspace(0.0, 1.0, 1000)
+            unSer1 = UnSerialized(a)
+            ser1 = ISerialized(unSer1)
+            td = ser1.getTypeDescriptor()
+            self.assert_(td == 'ndarray')
+            md = ser1.getMetadata()
+            self.assert_(md['shape'] == a.shape)
+            self.assert_(md['dtype'] == a.dtype.str)
+            buff = ser1.getData()
+            self.assert_(buff == numpy.getbuffer(a))
+            s = Serialized(buff, td, md)
+            us = IUnSerialized(s)
+            final = us.getObject()
+            self.assert_(numpy.getbuffer(a) == numpy.getbuffer(final))
+            self.assert_(a.dtype.str == final.dtype.str)
+            self.assert_(a.shape == final.shape)
+        
         
-        def testNDArraySerialized(self):
-            try:
-                import numpy
-            except ImportError:
-                pass
-            else:
-                a = numpy.linspace(0.0, 1.0, 1000)
-                unSer1 = UnSerialized(a)
-                ser1 = ISerialized(unSer1)
-                td = ser1.getTypeDescriptor()
-                self.assert_(td == 'ndarray')
-                md = ser1.getMetadata()
-                self.assert_(md['shape'] == a.shape)
-                self.assert_(md['dtype'] == a.dtype.str)
-                buff = ser1.getData()
-                self.assert_(buff == numpy.getbuffer(a))
-                s = Serialized(buff, td, md)
-                us = IUnSerialized(s)
-                final = us.getObject()
-                self.assert_(numpy.getbuffer(a) == numpy.getbuffer(final))
-                self.assert_(a.dtype.str == final.dtype.str)
-                self.assert_(a.shape == final.shape)
-            
-            
-    
  No newline at end of file

IPython/kernel/tests/test_pendingdeferred.py

@@ -1,186 +1,186
 #!/usr/bin/env python
 # encoding: utf-8
 
 """Tests for pendingdeferred.py"""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     from twisted.internet import defer
     from twisted.python import failure
 
     from IPython.testing.util import DeferredTestCase
     import IPython.kernel.pendingdeferred as pd
     from IPython.kernel import error
     from IPython.kernel.util import printer
 except ImportError:
-    pass
-else:
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
     
-    class Foo(object):
-    
-        def bar(self, bahz):
-            return defer.succeed('blahblah: %s' % bahz)
+class Foo(object):
 
-    class TwoPhaseFoo(pd.PendingDeferredManager):
-    
-        def __init__(self, foo):
-            self.foo = foo
-            pd.PendingDeferredManager.__init__(self)
+    def bar(self, bahz):
+        return defer.succeed('blahblah: %s' % bahz)
 
-        @pd.two_phase
-        def bar(self, bahz):
-            return self.foo.bar(bahz)
+class TwoPhaseFoo(pd.PendingDeferredManager):
 
-    class PendingDeferredManagerTest(DeferredTestCase):
-    
-        def setUp(self):
-            self.pdm = pd.PendingDeferredManager()
-        
-        def tearDown(self):
-            pass
-    
-        def testBasic(self):
-            dDict = {}
-            # Create 10 deferreds and save them
-            for i in range(10):
-                d = defer.Deferred()
-                did = self.pdm.save_pending_deferred(d)
-                dDict[did] = d
-            # Make sure they are begin saved
-            for k in dDict.keys():
-                self.assert_(self.pdm.quick_has_id(k))
-            # Get the pending deferred (block=True), then callback with 'foo' and compare
-            for did in dDict.keys()[0:5]:
-                d = self.pdm.get_pending_deferred(did,block=True)
-                dDict[did].callback('foo')
-                d.addCallback(lambda r: self.assert_(r=='foo'))
-            # Get the pending deferreds with (block=False) and make sure ResultNotCompleted is raised
-            for did in dDict.keys()[5:10]:
-                d = self.pdm.get_pending_deferred(did,block=False)
-                d.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
-            # Now callback the last 5, get them and compare.
-            for did in dDict.keys()[5:10]:
-                dDict[did].callback('foo')
-                d = self.pdm.get_pending_deferred(did,block=False)
-                d.addCallback(lambda r: self.assert_(r=='foo'))
-    
-        def test_save_then_delete(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            self.assert_(self.pdm.quick_has_id(did))
-            self.pdm.delete_pending_deferred(did)
-            self.assert_(not self.pdm.quick_has_id(did))
-    
-        def test_save_get_delete(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d2.addErrback(lambda f: self.assertRaises(error.AbortedPendingDeferredError, f.raiseException))
-            self.pdm.delete_pending_deferred(did)
-            return d2
-   
-        def test_double_get(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d3 = self.pdm.get_pending_deferred(did,True)
-            d3.addErrback(lambda f: self.assertRaises(error.InvalidDeferredID, f.raiseException))
-    
-        def test_get_after_callback(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d.callback('foo')
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d2.addCallback(lambda r: self.assertEquals(r,'foo'))
-            self.assert_(not self.pdm.quick_has_id(did))
+    def __init__(self, foo):
+        self.foo = foo
+        pd.PendingDeferredManager.__init__(self)
 
-        def test_get_before_callback(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d.callback('foo')
-            d2.addCallback(lambda r: self.assertEquals(r,'foo'))
-            self.assert_(not self.pdm.quick_has_id(did))
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d2.addCallback(lambda r: self.assertEquals(r,'foo'))
-            d.callback('foo')
-            self.assert_(not self.pdm.quick_has_id(did))
-    
-        def test_get_after_errback(self):
-            class MyError(Exception):
-                pass
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d.errback(failure.Failure(MyError('foo')))
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
-            self.assert_(not self.pdm.quick_has_id(did))
-
-        def test_get_before_errback(self):
-            class MyError(Exception):
-                pass
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d.errback(failure.Failure(MyError('foo')))
-            d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
-            self.assert_(not self.pdm.quick_has_id(did))
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
-            d.errback(failure.Failure(MyError('foo')))
-            self.assert_(not self.pdm.quick_has_id(did))
-        
-        def test_noresult_noblock(self):
-            d = defer.Deferred()
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,False)
-            d2.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
+    @pd.two_phase
+    def bar(self, bahz):
+        return self.foo.bar(bahz)
 
-        def test_with_callbacks(self):
-            d = defer.Deferred()
-            d.addCallback(lambda r: r+' foo')
-            d.addCallback(lambda r: r+' bar')
-            did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d.callback('bam')
-            d2.addCallback(lambda r: self.assertEquals(r,'bam foo bar'))
+class PendingDeferredManagerTest(DeferredTestCase):
+
+    def setUp(self):
+        self.pdm = pd.PendingDeferredManager()
     
-        def test_with_errbacks(self):
-            class MyError(Exception):
-                pass
+    def tearDown(self):
+        pass
+
+    def testBasic(self):
+        dDict = {}
+        # Create 10 deferreds and save them
+        for i in range(10):
             d = defer.Deferred()
-            d.addCallback(lambda r: 'foo')
-            d.addErrback(lambda f: 'caught error')
             did = self.pdm.save_pending_deferred(d)
-            d2 = self.pdm.get_pending_deferred(did,True)
-            d.errback(failure.Failure(MyError('bam')))
-            d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
+            dDict[did] = d
+        # Make sure they are begin saved
+        for k in dDict.keys():
+            self.assert_(self.pdm.quick_has_id(k))
+        # Get the pending deferred (block=True), then callback with 'foo' and compare
+        for did in dDict.keys()[0:5]:
+            d = self.pdm.get_pending_deferred(did,block=True)
+            dDict[did].callback('foo')
+            d.addCallback(lambda r: self.assert_(r=='foo'))
+        # Get the pending deferreds with (block=False) and make sure ResultNotCompleted is raised
+        for did in dDict.keys()[5:10]:
+            d = self.pdm.get_pending_deferred(did,block=False)
+            d.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
+        # Now callback the last 5, get them and compare.
+        for did in dDict.keys()[5:10]:
+            dDict[did].callback('foo')
+            d = self.pdm.get_pending_deferred(did,block=False)
+            d.addCallback(lambda r: self.assert_(r=='foo'))
+
+    def test_save_then_delete(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        self.assert_(self.pdm.quick_has_id(did))
+        self.pdm.delete_pending_deferred(did)
+        self.assert_(not self.pdm.quick_has_id(did))
+
+    def test_save_get_delete(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d2.addErrback(lambda f: self.assertRaises(error.AbortedPendingDeferredError, f.raiseException))
+        self.pdm.delete_pending_deferred(did)
+        return d2
+
+    def test_double_get(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d3 = self.pdm.get_pending_deferred(did,True)
+        d3.addErrback(lambda f: self.assertRaises(error.InvalidDeferredID, f.raiseException))
+
+    def test_get_after_callback(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d.callback('foo')
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d2.addCallback(lambda r: self.assertEquals(r,'foo'))
+        self.assert_(not self.pdm.quick_has_id(did))
+
+    def test_get_before_callback(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d.callback('foo')
+        d2.addCallback(lambda r: self.assertEquals(r,'foo'))
+        self.assert_(not self.pdm.quick_has_id(did))
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d2.addCallback(lambda r: self.assertEquals(r,'foo'))
+        d.callback('foo')
+        self.assert_(not self.pdm.quick_has_id(did))
+
+    def test_get_after_errback(self):
+        class MyError(Exception):
+            pass
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d.errback(failure.Failure(MyError('foo')))
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
+        self.assert_(not self.pdm.quick_has_id(did))
+
+    def test_get_before_errback(self):
+        class MyError(Exception):
+            pass
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d.errback(failure.Failure(MyError('foo')))
+        d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
+        self.assert_(not self.pdm.quick_has_id(did))
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
+        d.errback(failure.Failure(MyError('foo')))
+        self.assert_(not self.pdm.quick_has_id(did))
     
-        def test_nested_deferreds(self):
-            d = defer.Deferred()
-            d2 = defer.Deferred()
-            d.addCallback(lambda r: d2)
-            did = self.pdm.save_pending_deferred(d)
-            d.callback('foo')
-            d3 = self.pdm.get_pending_deferred(did,False)
-            d3.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
-            d2.callback('bar')
-            d3 = self.pdm.get_pending_deferred(did,False)
-            d3.addCallback(lambda r: self.assertEquals(r,'bar'))
+    def test_noresult_noblock(self):
+        d = defer.Deferred()
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,False)
+        d2.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
+
+    def test_with_callbacks(self):
+        d = defer.Deferred()
+        d.addCallback(lambda r: r+' foo')
+        d.addCallback(lambda r: r+' bar')
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d.callback('bam')
+        d2.addCallback(lambda r: self.assertEquals(r,'bam foo bar'))
+
+    def test_with_errbacks(self):
+        class MyError(Exception):
+            pass
+        d = defer.Deferred()
+        d.addCallback(lambda r: 'foo')
+        d.addErrback(lambda f: 'caught error')
+        did = self.pdm.save_pending_deferred(d)
+        d2 = self.pdm.get_pending_deferred(did,True)
+        d.errback(failure.Failure(MyError('bam')))
+        d2.addErrback(lambda f: self.assertRaises(MyError, f.raiseException))
+
+    def test_nested_deferreds(self):
+        d = defer.Deferred()
+        d2 = defer.Deferred()
+        d.addCallback(lambda r: d2)
+        did = self.pdm.save_pending_deferred(d)
+        d.callback('foo')
+        d3 = self.pdm.get_pending_deferred(did,False)
+        d3.addErrback(lambda f: self.assertRaises(error.ResultNotCompleted, f.raiseException))
+        d2.callback('bar')
+        d3 = self.pdm.get_pending_deferred(did,False)
+        d3.addCallback(lambda r: self.assertEquals(r,'bar'))
 

IPython/kernel/tests/test_task.py

@@ -1,50 +1,51
 # encoding: utf-8
 
 """This file contains unittests for the kernel.task.py module."""
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     import time
 
     from twisted.internet import defer
     from twisted.trial import unittest
 
     from IPython.kernel import task, controllerservice as cs, engineservice as es
     from IPython.kernel.multiengine import IMultiEngine
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.tests.tasktest import ITaskControllerTestCase
 except ImportError:
-    pass
-else:
-    #-------------------------------------------------------------------------------
-    # Tests
-    #-------------------------------------------------------------------------------
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
 
-    class BasicTaskControllerTestCase(DeferredTestCase, ITaskControllerTestCase):
+#-------------------------------------------------------------------------------
+# Tests
+#-------------------------------------------------------------------------------
+
+class BasicTaskControllerTestCase(DeferredTestCase, ITaskControllerTestCase):
+
+    def setUp(self):
+        self.controller  = cs.ControllerService()
+        self.controller.startService()
+        self.multiengine = IMultiEngine(self.controller)
+        self.tc = task.ITaskController(self.controller)
+        self.tc.failurePenalty = 0
+        self.engines=[]
     
-        def setUp(self):
-            self.controller  = cs.ControllerService()
-            self.controller.startService()
-            self.multiengine = IMultiEngine(self.controller)
-            self.tc = task.ITaskController(self.controller)
-            self.tc.failurePenalty = 0
-            self.engines=[]
-        
-        def tearDown(self):
-            self.controller.stopService()
-            for e in self.engines:
-                e.stopService()
+    def tearDown(self):
+        self.controller.stopService()
+        for e in self.engines:
+            e.stopService()
 
 

IPython/kernel/tests/test_taskfc.py

@@ -1,161 +1,162
 #!/usr/bin/env python
 # encoding: utf-8
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 try:
     import time
 
     from twisted.internet import defer, reactor
 
     from IPython.kernel.fcutil import Tub, UnauthenticatedTub
 
     from IPython.kernel import task as taskmodule
     from IPython.kernel import controllerservice as cs
     import IPython.kernel.multiengine as me
     from IPython.testing.util import DeferredTestCase
     from IPython.kernel.multienginefc import IFCSynchronousMultiEngine
     from IPython.kernel.taskfc import IFCTaskController
     from IPython.kernel.util import printer
     from IPython.kernel.tests.tasktest import ITaskControllerTestCase
     from IPython.kernel.clientconnector import ClientConnector
     from IPython.kernel.error import CompositeError
     from IPython.kernel.parallelfunction import ParallelFunction
 except ImportError:
-    pass
-else:
+    import nose
+    raise nose.SkipTest("This test requires zope.interface, Twisted and Foolscap")
 
-    #-------------------------------------------------------------------------------
-    # Tests
-    #-------------------------------------------------------------------------------
 
-    def _raise_it(f):
-        try:
-            f.raiseException()
-        except CompositeError, e:
-            e.raise_exception()
+#-------------------------------------------------------------------------------
+# Tests
+#-------------------------------------------------------------------------------
 
-    class TaskTest(DeferredTestCase, ITaskControllerTestCase):
+def _raise_it(f):
+    try:
+        f.raiseException()
+    except CompositeError, e:
+        e.raise_exception()
 
-        def setUp(self):
-        
-            self.engines = []
-                
-            self.controller = cs.ControllerService()
-            self.controller.startService()
-            self.imultiengine = me.IMultiEngine(self.controller)
-            self.itc = taskmodule.ITaskController(self.controller)
-            self.itc.failurePenalty = 0
-        
-            self.mec_referenceable = IFCSynchronousMultiEngine(self.imultiengine)
-            self.tc_referenceable = IFCTaskController(self.itc)
-        
-            self.controller_tub = Tub()
-            self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
-            self.controller_tub.setLocation('127.0.0.1:10105')
-        
-            mec_furl = self.controller_tub.registerReference(self.mec_referenceable)
-            tc_furl = self.controller_tub.registerReference(self.tc_referenceable)
-            self.controller_tub.startService()
-        
-            self.client_tub = ClientConnector()
-            d = self.client_tub.get_multiengine_client(mec_furl)
-            d.addCallback(self.handle_mec_client)
-            d.addCallback(lambda _: self.client_tub.get_task_client(tc_furl))
-            d.addCallback(self.handle_tc_client)
-            return d
-        
-        def handle_mec_client(self, client):
-            self.multiengine = client
+class TaskTest(DeferredTestCase, ITaskControllerTestCase):
+
+    def setUp(self):
+    
+        self.engines = []
+            
+        self.controller = cs.ControllerService()
+        self.controller.startService()
+        self.imultiengine = me.IMultiEngine(self.controller)
+        self.itc = taskmodule.ITaskController(self.controller)
+        self.itc.failurePenalty = 0
+    
+        self.mec_referenceable = IFCSynchronousMultiEngine(self.imultiengine)
+        self.tc_referenceable = IFCTaskController(self.itc)
+    
+        self.controller_tub = Tub()
+        self.controller_tub.listenOn('tcp:10105:interface=127.0.0.1')
+        self.controller_tub.setLocation('127.0.0.1:10105')
+    
+        mec_furl = self.controller_tub.registerReference(self.mec_referenceable)
+        tc_furl = self.controller_tub.registerReference(self.tc_referenceable)
+        self.controller_tub.startService()
+    
+        self.client_tub = ClientConnector()
+        d = self.client_tub.get_multiengine_client(mec_furl)
+        d.addCallback(self.handle_mec_client)
+        d.addCallback(lambda _: self.client_tub.get_task_client(tc_furl))
+        d.addCallback(self.handle_tc_client)
+        return d
+    
+    def handle_mec_client(self, client):
+        self.multiengine = client
+
+    def handle_tc_client(self, client):
+        self.tc = client
+
+    def tearDown(self):
+        dlist = []
+        # Shut down the multiengine client
+        d = self.client_tub.tub.stopService()
+        dlist.append(d)
+        # Shut down the engines
+        for e in self.engines:
+            e.stopService()
+        # Shut down the controller
+        d = self.controller_tub.stopService()
+        d.addBoth(lambda _: self.controller.stopService())
+        dlist.append(d)
+        return defer.DeferredList(dlist)
+    
+    def test_mapper(self):
+        self.addEngine(1)
+        m = self.tc.mapper()
+        self.assertEquals(m.task_controller,self.tc)
+        self.assertEquals(m.clear_before,False)
+        self.assertEquals(m.clear_after,False)
+        self.assertEquals(m.retries,0)
+        self.assertEquals(m.recovery_task,None)
+        self.assertEquals(m.depend,None)
+        self.assertEquals(m.block,True)
+    
+    def test_map_default(self):
+        self.addEngine(1)
+        m = self.tc.mapper()
+        d = m.map(lambda x: 2*x, range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        d.addCallback(lambda _: self.tc.map(lambda x: 2*x, range(10)))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
+    
+    def test_map_noblock(self):
+        self.addEngine(1)
+        m = self.tc.mapper(block=False)
+        d = m.map(lambda x: 2*x, range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[x for x in range(10)]))
+        return d
+            
+    def test_mapper_fail(self):
+        self.addEngine(1)
+        m = self.tc.mapper()
+        d = m.map(lambda x: 1/0, range(10))
+        d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
+        return d
+    
+    def test_parallel(self):
+        self.addEngine(1)
+        p = self.tc.parallel()
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 2*x
+        d = f(range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
+        return d
     
-        def handle_tc_client(self, client):
-            self.tc = client
+    def test_parallel_noblock(self):
+        self.addEngine(1)
+        p = self.tc.parallel(block=False)
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 2*x
+        d = f(range(10))
+        d.addCallback(lambda r: self.assertEquals(r,[x for x in range(10)]))
+        return d
     
-        def tearDown(self):
-            dlist = []
-            # Shut down the multiengine client
-            d = self.client_tub.tub.stopService()
-            dlist.append(d)
-            # Shut down the engines
-            for e in self.engines:
-                e.stopService()
-            # Shut down the controller
-            d = self.controller_tub.stopService()
-            d.addBoth(lambda _: self.controller.stopService())
-            dlist.append(d)
-            return defer.DeferredList(dlist)
-        
-        def test_mapper(self):
-            self.addEngine(1)
-            m = self.tc.mapper()
-            self.assertEquals(m.task_controller,self.tc)
-            self.assertEquals(m.clear_before,False)
-            self.assertEquals(m.clear_after,False)
-            self.assertEquals(m.retries,0)
-            self.assertEquals(m.recovery_task,None)
-            self.assertEquals(m.depend,None)
-            self.assertEquals(m.block,True)
-        
-        def test_map_default(self):
-            self.addEngine(1)
-            m = self.tc.mapper()
-            d = m.map(lambda x: 2*x, range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            d.addCallback(lambda _: self.tc.map(lambda x: 2*x, range(10)))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-        
-        def test_map_noblock(self):
-            self.addEngine(1)
-            m = self.tc.mapper(block=False)
-            d = m.map(lambda x: 2*x, range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[x for x in range(10)]))
-            return d
-                
-        def test_mapper_fail(self):
-            self.addEngine(1)
-            m = self.tc.mapper()
-            d = m.map(lambda x: 1/0, range(10))
-            d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
-            return d
-        
-        def test_parallel(self):
-            self.addEngine(1)
-            p = self.tc.parallel()
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 2*x
-            d = f(range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[2*x for x in range(10)]))
-            return d
-        
-        def test_parallel_noblock(self):
-            self.addEngine(1)
-            p = self.tc.parallel(block=False)
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 2*x
-            d = f(range(10))
-            d.addCallback(lambda r: self.assertEquals(r,[x for x in range(10)]))
-            return d
-        
-        def test_parallel_fail(self):
-            self.addEngine(1)
-            p = self.tc.parallel()
-            self.assert_(isinstance(p, ParallelFunction))
-            @p
-            def f(x): return 1/0
-            d = f(range(10))
-            d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
-            return d
  No newline at end of file
+    def test_parallel_fail(self):
+        self.addEngine(1)
+        p = self.tc.parallel()
+        self.assert_(isinstance(p, ParallelFunction))
+        @p
+        def f(x): return 1/0
+        d = f(range(10))
+        d.addBoth(lambda f: self.assertRaises(ZeroDivisionError, _raise_it, f))
+        return d
  No newline at end of file

IPython/testing/decorators.py

@@ -1,135 +1,160
 """Decorators for labeling test objects.
 
 Decorators that merely return a modified version of the original
 function object are straightforward.  Decorators that return a new
 function object need to use
 nose.tools.make_decorator(original_function)(decorator) in returning
 the decorator, in order to preserve metadata such as function name,
 setup and teardown functions and so on - see nose.tools for more
 information.
 
+This module provides a set of useful decorators meant to be ready to use in
+your own tests.  See the bottom of the file for the ready-made ones, and if you
+find yourself writing a new one that may be of generic use, add it here.
+
 NOTE: This file contains IPython-specific decorators and imports the
 numpy.testing.decorators file, which we've copied verbatim.  Any of our own
 code will be added at the bottom if we end up extending this.
 """
 
 # Stdlib imports
 import inspect
+import sys
 
 # Third-party imports
 
 # This is Michele Simionato's decorator module, also kept verbatim.
 from decorator_msim import decorator, update_wrapper
 
 # Grab the numpy-specific decorators which we keep in a file that we
 # occasionally update from upstream: decorators_numpy.py is an IDENTICAL copy
 # of numpy.testing.decorators.
 from decorators_numpy import *
 
 ##############################################################################
 # Local code begins
 
 # Utility functions
 
 def apply_wrapper(wrapper,func):
     """Apply a wrapper to a function for decoration.
 
     This mixes Michele Simionato's decorator tool with nose's make_decorator,
     to apply a wrapper in a decorator so that all nose attributes, as well as
     function signature and other properties, survive the decoration cleanly.
     This will ensure that wrapped functions can still be well introspected via
     IPython, for example.
     """
     import nose.tools
 
     return decorator(wrapper,nose.tools.make_decorator(func)(wrapper))
 
 
 def make_label_dec(label,ds=None):
     """Factory function to create a decorator that applies one or more labels.
 
     :Parameters:
       label : string or sequence
       One or more labels that will be applied by the decorator to the functions
     it decorates.  Labels are attributes of the decorated function with their
     value set to True.
 
     :Keywords:
       ds : string
       An optional docstring for the resulting decorator.  If not given, a
       default docstring is auto-generated.
 
     :Returns:
       A decorator.
 
     :Examples:
 
     A simple labeling decorator:
     >>> slow = make_label_dec('slow')
     >>> print slow.__doc__
     Labels a test as 'slow'.
 
     And one that uses multiple labels and a custom docstring:
     >>> rare = make_label_dec(['slow','hard'],
     ... "Mix labels 'slow' and 'hard' for rare tests.")
     >>> print rare.__doc__
     Mix labels 'slow' and 'hard' for rare tests.
 
     Now, let's test using this one:
     >>> @rare
     ... def f(): pass
     ...
     >>>
     >>> f.slow
     True
     >>> f.hard
     True
     """
 
     if isinstance(label,basestring):
         labels = [label]
     else:
         labels = label
         
     # Validate that the given label(s) are OK for use in setattr() by doing a
     # dry run on a dummy function.
     tmp = lambda : None
     for label in labels:
         setattr(tmp,label,True)
 
     # This is the actual decorator we'll return
     def decor(f):
         for label in labels:
             setattr(f,label,True)
         return f
     
     # Apply the user's docstring, or autogenerate a basic one
     if ds is None:
         ds = "Labels a test as %r." % label
     decor.__doc__ = ds
     
     return decor
 
 #-----------------------------------------------------------------------------
 # Decorators for public use
 
 skip_doctest = make_label_dec('skip_doctest',
     """Decorator - mark a function or method for skipping its doctest.
 
     This decorator allows you to mark a function whose docstring you wish to
     omit from testing, while preserving the docstring for introspection, help,
     etc.""")                              
 
+def skip(msg=''):
+    """Decorator - mark a test function for skipping from test suite.
+
+    This function *is* already a decorator, it is not a factory like
+    make_label_dec or some of those in decorators_numpy.
+
+    :Parameters:
+
+      func : function
+        Test function to be skipped
 
-def skip(func):
-    """Decorator - mark a test function for skipping from test suite."""
+      msg : string
+        Optional message to be added.
+      """
 
     import nose
-    
-    def wrapper(*a,**k):
-        raise nose.SkipTest("Skipping test for function: %s" %
-                            func.__name__)
-    
-    return apply_wrapper(wrapper,func)
 
+    def inner(func):
+
+        def wrapper(*a,**k):
+            if msg: out = '\n'+msg
+            else: out = ''
+            raise nose.SkipTest("Skipping test for function: %s%s" %
+                                (func.__name__,out))
+
+        return apply_wrapper(wrapper,func)
+
+    return inner
 
+# Decorators to skip certain tests on specific platforms.
+skip_win32 = skipif(sys.platform=='win32',"This test does not run under Windows")
+skip_linux = skipif(sys.platform=='linux2',"This test does not run under Linux")
+skip_osx = skipif(sys.platform=='darwin',"This test does not run under OSX")

IPython/testing/plugin/Makefile

@@ -1,75 +1,74
 # Set this prefix to where you want to install the plugin
-PREFIX=~/usr/local
-PREFIX=~/tmp/local
+PREFIX=/usr/local
 
 NOSE0=nosetests -vs --with-doctest --doctest-tests --detailed-errors
 NOSE=nosetests -vvs --with-ipdoctest --doctest-tests --doctest-extension=txt \
 --detailed-errors
 
 SRC=ipdoctest.py setup.py ../decorators.py
 
 # Default target for clean 'make'
 default: iplib
 
 # The actual plugin installation
 plugin: IPython_doctest_plugin.egg-info
 
 # Simple targets that test one thing
 simple: plugin simple.py
 	$(NOSE) simple.py
 
 dtest: plugin dtexample.py
 	$(NOSE) dtexample.py
 
 rtest: plugin test_refs.py
 	$(NOSE) test_refs.py
 
 test: plugin dtexample.py
 	$(NOSE) dtexample.py test*.py test*.txt
 
 deb: plugin dtexample.py
 	$(NOSE) test_combo.txt
 
 # IPython tests
 deco:
 	$(NOSE0) IPython.testing.decorators
 
 magic: plugin
 	$(NOSE) IPython.Magic
 
 ipipe: plugin
 	$(NOSE) IPython.Extensions.ipipe
 
 iplib: plugin
 	$(NOSE)  IPython.iplib
 
 strd: plugin
 	$(NOSE) IPython.strdispatch
 
 engine: plugin
 	$(NOSE) IPython.kernel
 
 tf: plugin
 	$(NOSE) IPython.config.traitlets
 
 # All of ipython itself
 ipython: plugin
 	$(NOSE) IPython
 
 
 # Combined targets
 sr: rtest strd
 
 base: dtest rtest test strd deco
 
 quick: base iplib ipipe
 
 all: base ipython
 
 # Main plugin and cleanup
 IPython_doctest_plugin.egg-info: $(SRC)
 	python setup.py install --prefix=$(PREFIX)
 	touch $@
 
 clean:
 	rm -rf IPython_doctest_plugin.egg-info *~ *pyc build/ dist/

IPython/testing/plugin/ipdoctest.py

@@ -1,784 +1,806
 """Nose Plugin that supports IPython doctests.
 
 Limitations:
 
 - When generating examples for use as doctests, make sure that you have
   pretty-printing OFF.  This can be done either by starting ipython with the
   flag '--nopprint', by setting pprint to 0 in your ipythonrc file, or by
   interactively disabling it with %Pprint.  This is required so that IPython
   output matches that of normal Python, which is used by doctest for internal
   execution.
 
 - Do not rely on specific prompt numbers for results (such as using
   '_34==True', for example).  For IPython tests run via an external process the
   prompt numbers may be different, and IPython tests run as normal python code
   won't even have these special _NN variables set at all.
 """
 
 
 #-----------------------------------------------------------------------------
 # Module imports
 
 # From the standard library
 import __builtin__
 import commands
 import doctest
 import inspect
 import logging
 import os
 import re
 import sys
 import traceback
 import unittest
 
 from inspect import getmodule
 from StringIO import StringIO
 
 # We are overriding the default doctest runner, so we need to import a few
 # things from doctest directly
 from doctest import (REPORTING_FLAGS, REPORT_ONLY_FIRST_FAILURE,
                      _unittest_reportflags, DocTestRunner,
                      _extract_future_flags, pdb, _OutputRedirectingPdb,
                      _exception_traceback,
                      linecache)
 
 # Third-party modules
 import nose.core
 
 from nose.plugins import doctests, Plugin
 from nose.util import anyp, getpackage, test_address, resolve_name, tolist
 
 #-----------------------------------------------------------------------------
 # Module globals and other constants
 
 log = logging.getLogger(__name__)
 
 ###########################################################################
 # *** HACK ***
 # We must start our own ipython object and heavily muck with it so that all the
 # modifications IPython makes to system behavior don't send the doctest
 # machinery into a fit.  This code should be considered a gross hack, but it
 # gets the job done.
 
 
 # Hack to modify the %run command so we can sync the user's namespace with the
 # test globals.  Once we move over to a clean magic system, this will be done
 # with much less ugliness.
 
 def _run_ns_sync(self,arg_s,runner=None):
     """Modified version of %run that syncs testing namespaces.
 
     This is strictly needed for running doctests that call %run.
     """
 
     out = _ip.IP.magic_run_ori(arg_s,runner)
     _run_ns_sync.test_globs.update(_ip.user_ns)
     return out
 
 
 class ipnsdict(dict):
     """A special subclass of dict for use as an IPython namespace in doctests.
 
     This subclass adds a simple checkpointing capability so that when testing
     machinery clears it (we use it as the test execution context), it doesn't
     get completely destroyed.
     """
     
     def __init__(self,*a):
         dict.__init__(self,*a)
         self._savedict = {}
         
     def clear(self):
         dict.clear(self)
         self.update(self._savedict)
 
     def _checkpoint(self):
         self._savedict.clear()
         self._savedict.update(self)
 
     def update(self,other):
         self._checkpoint()
         dict.update(self,other)
         # If '_' is in the namespace, python won't set it when executing code,
         # and we have examples that test it.  So we ensure that the namespace
         # is always 'clean' of it before it's used for test code execution.
         self.pop('_',None)
         
 
 def start_ipython():
     """Start a global IPython shell, which we need for IPython-specific syntax.
     """
     import new
 
     import IPython
 
     def xsys(cmd):
         """Execute a command and print its output.
 
         This is just a convenience function to replace the IPython system call
         with one that is more doctest-friendly.
         """
         cmd = _ip.IP.var_expand(cmd,depth=1)
         sys.stdout.write(commands.getoutput(cmd))
         sys.stdout.flush()
 
     # Store certain global objects that IPython modifies
     _displayhook = sys.displayhook
     _excepthook = sys.excepthook
     _main = sys.modules.get('__main__')
 
     # Start IPython instance.  We customize it to start with minimal frills.
     user_ns,global_ns = IPython.ipapi.make_user_namespaces(ipnsdict(),dict())
     
     IPython.Shell.IPShell(['--classic','--noterm_title'],
                           user_ns,global_ns)
 
     # Deactivate the various python system hooks added by ipython for
     # interactive convenience so we don't confuse the doctest system
     sys.modules['__main__'] = _main
     sys.displayhook = _displayhook
     sys.excepthook = _excepthook
 
     # So that ipython magics and aliases can be doctested (they work by making
     # a call into a global _ip object)
     _ip = IPython.ipapi.get()
     __builtin__._ip = _ip
 
     # Modify the IPython system call with one that uses getoutput, so that we
     # can capture subcommands and print them to Python's stdout, otherwise the
     # doctest machinery would miss them.
     _ip.system = xsys
 
     # Also patch our %run function in.
     im = new.instancemethod(_run_ns_sync,_ip.IP, _ip.IP.__class__)
     _ip.IP.magic_run_ori = _ip.IP.magic_run
     _ip.IP.magic_run = im
 
 # The start call MUST be made here.  I'm not sure yet why it doesn't work if
 # it is made later, at plugin initialization time, but in all my tests, that's
 # the case.
 start_ipython()
 
 # *** END HACK ***
 ###########################################################################
 
 # Classes and functions
 
 def is_extension_module(filename):
     """Return whether the given filename is an extension module.
 
     This simply checks that the extension is either .so or .pyd.
     """
     return os.path.splitext(filename)[1].lower() in ('.so','.pyd')
 
 
 class nodoc(object):
     def __init__(self,obj):
         self.obj = obj
 
     def __getattribute__(self,key):
         if key == '__doc__':
             return None
         else:
             return getattr(object.__getattribute__(self,'obj'),key)
 
 # Modified version of the one in the stdlib, that fixes a python bug (doctests
 # not found in extension modules, http://bugs.python.org/issue3158)
 class DocTestFinder(doctest.DocTestFinder):
 
     def _from_module(self, module, object):
         """
         Return true if the given object is defined in the given
         module.
         """
         if module is None:
             return True
         elif inspect.isfunction(object):
             return module.__dict__ is object.func_globals
         elif inspect.isbuiltin(object):
             return module.__name__ == object.__module__
         elif inspect.isclass(object):
             return module.__name__ == object.__module__
         elif inspect.ismethod(object):
             # This one may be a bug in cython that fails to correctly set the
             # __module__ attribute of methods, but since the same error is easy
             # to make by extension code writers, having this safety in place
             # isn't such a bad idea
             return module.__name__ == object.im_class.__module__
         elif inspect.getmodule(object) is not None:
             return module is inspect.getmodule(object)
         elif hasattr(object, '__module__'):
             return module.__name__ == object.__module__
         elif isinstance(object, property):
             return True # [XX] no way not be sure.
         else:
             raise ValueError("object must be a class or function")
 
     def _find(self, tests, obj, name, module, source_lines, globs, seen):
         """
         Find tests for the given object and any contained objects, and
         add them to `tests`.
         """
 
         if hasattr(obj,"skip_doctest"):
             #print 'SKIPPING DOCTEST FOR:',obj  # dbg
             obj = nodoc(obj)
 
         doctest.DocTestFinder._find(self,tests, obj, name, module,
                                     source_lines, globs, seen)
 
         # Below we re-run pieces of the above method with manual modifications,
         # because the original code is buggy and fails to correctly identify
         # doctests in extension modules.
 
         # Local shorthands
         from inspect import isroutine, isclass, ismodule
 
         # Look for tests in a module's contained objects.
         if inspect.ismodule(obj) and self._recurse:
             for valname, val in obj.__dict__.items():
                 valname1 = '%s.%s' % (name, valname)
                 if ( (isroutine(val) or isclass(val))
                      and self._from_module(module, val) ):
 
                     self._find(tests, val, valname1, module, source_lines,
                                globs, seen)
 
         # Look for tests in a class's contained objects.
         if inspect.isclass(obj) and self._recurse:
             #print 'RECURSE into class:',obj  # dbg
             for valname, val in obj.__dict__.items():
                 # Special handling for staticmethod/classmethod.
                 if isinstance(val, staticmethod):
                     val = getattr(obj, valname)
                 if isinstance(val, classmethod):
                     val = getattr(obj, valname).im_func
 
                 # Recurse to methods, properties, and nested classes.
                 if ((inspect.isfunction(val) or inspect.isclass(val) or
                      inspect.ismethod(val) or
                       isinstance(val, property)) and
                       self._from_module(module, val)):
                     valname = '%s.%s' % (name, valname)
                     self._find(tests, val, valname, module, source_lines,
                                globs, seen)
 
 
 class IPDoctestOutputChecker(doctest.OutputChecker):
     """Second-chance checker with support for random tests.
     
     If the default comparison doesn't pass, this checker looks in the expected
     output string for flags that tell us to ignore the output.
     """
 
     random_re = re.compile(r'#\s*random\s+')
     
     def check_output(self, want, got, optionflags):
         """Check output, accepting special markers embedded in the output.
 
         If the output didn't pass the default validation but the special string
         '#random' is included, we accept it."""
 
         # Let the original tester verify first, in case people have valid tests
         # that happen to have a comment saying '#random' embedded in.
         ret = doctest.OutputChecker.check_output(self, want, got,
                                                  optionflags)
         if not ret and self.random_re.search(want):
             #print >> sys.stderr, 'RANDOM OK:',want  # dbg
             return True
 
         return ret
 
 
 class DocTestCase(doctests.DocTestCase):
     """Proxy for DocTestCase: provides an address() method that
     returns the correct address for the doctest case. Otherwise
     acts as a proxy to the test case. To provide hints for address(),
     an obj may also be passed -- this will be used as the test object
     for purposes of determining the test address, if it is provided.
     """
 
     # Note: this method was taken from numpy's nosetester module.
 
     # Subclass nose.plugins.doctests.DocTestCase to work around a bug in
     # its constructor that blocks non-default arguments from being passed
     # down into doctest.DocTestCase
 
     def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
                  checker=None, obj=None, result_var='_'):
         self._result_var = result_var
         doctests.DocTestCase.__init__(self, test,
                                       optionflags=optionflags,
                                       setUp=setUp, tearDown=tearDown,
                                       checker=checker)
         # Now we must actually copy the original constructor from the stdlib
         # doctest class, because we can't call it directly and a bug in nose
         # means it never gets passed the right arguments.
 
         self._dt_optionflags = optionflags
         self._dt_checker = checker
         self._dt_test = test
         self._dt_setUp = setUp
         self._dt_tearDown = tearDown
 
         # XXX - store this runner once in the object!
         runner = IPDocTestRunner(optionflags=optionflags,
                                  checker=checker, verbose=False)
         self._dt_runner = runner
 
 
         # Each doctest should remember what directory it was loaded from...
         self._ori_dir = os.getcwd()
 
     # Modified runTest from the default stdlib
     def runTest(self):
         test = self._dt_test
         runner = self._dt_runner
         
         old = sys.stdout
         new = StringIO()
         optionflags = self._dt_optionflags
 
         if not (optionflags & REPORTING_FLAGS):
             # The option flags don't include any reporting flags,
             # so add the default reporting flags
             optionflags |= _unittest_reportflags
 
         try:
             # Save our current directory and switch out to the one where the
             # test was originally created, in case another doctest did a
             # directory change.  We'll restore this in the finally clause.
             curdir = os.getcwd()
             os.chdir(self._ori_dir)
 
             runner.DIVIDER = "-"*70
             failures, tries = runner.run(test,out=new.write,
                                          clear_globs=False)
         finally:
             sys.stdout = old
             os.chdir(curdir)
 
         if failures:
             raise self.failureException(self.format_failure(new.getvalue()))
 
     def setUp(self):
         """Modified test setup that syncs with ipython namespace"""
         
         if isinstance(self._dt_test.examples[0],IPExample):
             # for IPython examples *only*, we swap the globals with the ipython
             # namespace, after updating it with the globals (which doctest
             # fills with the necessary info from the module being tested).
             _ip.IP.user_ns.update(self._dt_test.globs)
             self._dt_test.globs = _ip.IP.user_ns
 
         doctests.DocTestCase.setUp(self)
     
 
 
 # A simple subclassing of the original with a different class name, so we can
 # distinguish and treat differently IPython examples from pure python ones.
 class IPExample(doctest.Example): pass
 
 
 class IPExternalExample(doctest.Example):
     """Doctest examples to be run in an external process."""
 
     def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
                  options=None):
         # Parent constructor
         doctest.Example.__init__(self,source,want,exc_msg,lineno,indent,options)
 
         # An EXTRA newline is needed to prevent pexpect hangs
         self.source += '\n'
 
 
 class IPDocTestParser(doctest.DocTestParser):
     """
     A class used to parse strings containing doctest examples.
 
     Note: This is a version modified to properly recognize IPython input and
     convert any IPython examples into valid Python ones.
     """
     # This regular expression is used to find doctest examples in a
     # string.  It defines three groups: `source` is the source code
     # (including leading indentation and prompts); `indent` is the
     # indentation of the first (PS1) line of the source code; and
     # `want` is the expected output (including leading indentation).
 
     # Classic Python prompts or default IPython ones
     _PS1_PY = r'>>>'
     _PS2_PY = r'\.\.\.'
 
     _PS1_IP = r'In\ \[\d+\]:'
     _PS2_IP = r'\ \ \ \.\.\.+:'
 
     _RE_TPL = r'''
         # Source consists of a PS1 line followed by zero or more PS2 lines.
         (?P<source>
             (?:^(?P<indent> [ ]*) (?P<ps1> %s) .*)    # PS1 line
             (?:\n           [ ]*  (?P<ps2> %s) .*)*)  # PS2 lines
         \n? # a newline
         # Want consists of any non-blank lines that do not start with PS1.
         (?P<want> (?:(?![ ]*$)    # Not a blank line
                      (?![ ]*%s)   # Not a line starting with PS1
                      (?![ ]*%s)   # Not a line starting with PS2
                      .*$\n?       # But any other line
                   )*)
                   '''
 
     _EXAMPLE_RE_PY = re.compile( _RE_TPL % (_PS1_PY,_PS2_PY,_PS1_PY,_PS2_PY),
                                  re.MULTILINE | re.VERBOSE)
 
     _EXAMPLE_RE_IP = re.compile( _RE_TPL % (_PS1_IP,_PS2_IP,_PS1_IP,_PS2_IP),
                                  re.MULTILINE | re.VERBOSE)
 
     # Mark a test as being fully random.  In this case, we simply append the
     # random marker ('#random') to each individual example's output.  This way
     # we don't need to modify any other code.
     _RANDOM_TEST = re.compile(r'#\s*all-random\s+')
 
     # Mark tests to be executed in an external process - currently unsupported.
     _EXTERNAL_IP = re.compile(r'#\s*ipdoctest:\s*EXTERNAL')
     
     def ip2py(self,source):
         """Convert input IPython source into valid Python."""
         out = []
         newline = out.append
         for lnum,line in enumerate(source.splitlines()):
             newline(_ip.IP.prefilter(line,lnum>0))
         newline('')  # ensure a closing newline, needed by doctest
         #print "PYSRC:", '\n'.join(out)  # dbg
         return '\n'.join(out)
 
     def parse(self, string, name='<string>'):
         """
         Divide the given string into examples and intervening text,
         and return them as a list of alternating Examples and strings.
         Line numbers for the Examples are 0-based.  The optional
         argument `name` is a name identifying this string, and is only
         used for error messages.
         """
 
         #print 'Parse string:\n',string # dbg
 
         string = string.expandtabs()
         # If all lines begin with the same indentation, then strip it.
         min_indent = self._min_indent(string)
         if min_indent > 0:
             string = '\n'.join([l[min_indent:] for l in string.split('\n')])
 
         output = []
         charno, lineno = 0, 0
 
         # We make 'all random' tests by adding the '# random' mark to every
         # block of output in the test.
         if self._RANDOM_TEST.search(string):
             random_marker = '\n# random'
         else:
             random_marker = ''
 
         # Whether to convert the input from ipython to python syntax
         ip2py = False
         # Find all doctest examples in the string.  First, try them as Python
         # examples, then as IPython ones
         terms = list(self._EXAMPLE_RE_PY.finditer(string))
         if terms:
             # Normal Python example
             #print '-'*70  # dbg
             #print 'PyExample, Source:\n',string  # dbg
             #print '-'*70  # dbg
             Example = doctest.Example
         else:
             # It's an ipython example.  Note that IPExamples are run
             # in-process, so their syntax must be turned into valid python.
             # IPExternalExamples are run out-of-process (via pexpect) so they
             # don't need any filtering (a real ipython will be executing them).
             terms = list(self._EXAMPLE_RE_IP.finditer(string))
             if self._EXTERNAL_IP.search(string):
                 #print '-'*70  # dbg
                 #print 'IPExternalExample, Source:\n',string  # dbg
                 #print '-'*70  # dbg
                 Example = IPExternalExample
             else:
                 #print '-'*70  # dbg
                 #print 'IPExample, Source:\n',string  # dbg
                 #print '-'*70  # dbg
                 Example = IPExample
                 ip2py = True
 
         for m in terms:
             # Add the pre-example text to `output`.
             output.append(string[charno:m.start()])
             # Update lineno (lines before this example)
             lineno += string.count('\n', charno, m.start())
             # Extract info from the regexp match.
             (source, options, want, exc_msg) = \
                      self._parse_example(m, name, lineno,ip2py)
 
             # Append the random-output marker (it defaults to empty in most
             # cases, it's only non-empty for 'all-random' tests):
             want += random_marker
                 
             if Example is IPExternalExample:
                 options[doctest.NORMALIZE_WHITESPACE] = True
                 want += '\n'
 
             # Create an Example, and add it to the list.
             if not self._IS_BLANK_OR_COMMENT(source):
                 output.append(Example(source, want, exc_msg,
                                       lineno=lineno,
                                       indent=min_indent+len(m.group('indent')),
                                       options=options))
             # Update lineno (lines inside this example)
             lineno += string.count('\n', m.start(), m.end())
             # Update charno.
             charno = m.end()
         # Add any remaining post-example text to `output`.
         output.append(string[charno:])
         return output
 
     def _parse_example(self, m, name, lineno,ip2py=False):
         """
         Given a regular expression match from `_EXAMPLE_RE` (`m`),
         return a pair `(source, want)`, where `source` is the matched
         example's source code (with prompts and indentation stripped);
         and `want` is the example's expected output (with indentation
         stripped).
 
         `name` is the string's name, and `lineno` is the line number
         where the example starts; both are used for error messages.
 
         Optional:
         `ip2py`: if true, filter the input via IPython to convert the syntax
         into valid python.
         """
 
         # Get the example's indentation level.
         indent = len(m.group('indent'))
 
         # Divide source into lines; check that they're properly
         # indented; and then strip their indentation & prompts.
         source_lines = m.group('source').split('\n')
 
         # We're using variable-length input prompts
         ps1 = m.group('ps1')
         ps2 = m.group('ps2')
         ps1_len = len(ps1)
 
         self._check_prompt_blank(source_lines, indent, name, lineno,ps1_len)
         if ps2:
             self._check_prefix(source_lines[1:], ' '*indent + ps2, name, lineno)
 
         source = '\n'.join([sl[indent+ps1_len+1:] for sl in source_lines])
 
         if ip2py:
             # Convert source input from IPython into valid Python syntax
             source = self.ip2py(source)
 
         # Divide want into lines; check that it's properly indented; and
         # then strip the indentation.  Spaces before the last newline should
         # be preserved, so plain rstrip() isn't good enough.
         want = m.group('want')
         want_lines = want.split('\n')
         if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
             del want_lines[-1]  # forget final newline & spaces after it
         self._check_prefix(want_lines, ' '*indent, name,
                            lineno + len(source_lines))
 
         # Remove ipython output prompt that might be present in the first line
         want_lines[0] = re.sub(r'Out\[\d+\]: \s*?\n?','',want_lines[0])
 
         want = '\n'.join([wl[indent:] for wl in want_lines])
 
         # If `want` contains a traceback message, then extract it.
         m = self._EXCEPTION_RE.match(want)
         if m:
             exc_msg = m.group('msg')
         else:
             exc_msg = None
 
         # Extract options from the source.
         options = self._find_options(source, name, lineno)
 
         return source, options, want, exc_msg
 
     def _check_prompt_blank(self, lines, indent, name, lineno, ps1_len):
         """
         Given the lines of a source string (including prompts and
         leading indentation), check to make sure that every prompt is
         followed by a space character.  If any line is not followed by
         a space character, then raise ValueError.
 
         Note: IPython-modified version which takes the input prompt length as a
         parameter, so that prompts of variable length can be dealt with.
         """
         space_idx = indent+ps1_len
         min_len = space_idx+1
         for i, line in enumerate(lines):
             if len(line) >=  min_len and line[space_idx] != ' ':
                 raise ValueError('line %r of the docstring for %s '
                                  'lacks blank after %s: %r' %
                                  (lineno+i+1, name,
                                   line[indent:space_idx], line))
 
 
 SKIP = doctest.register_optionflag('SKIP')
 
 
 class IPDocTestRunner(doctest.DocTestRunner,object):
     """Test runner that synchronizes the IPython namespace with test globals.
     """
     
     def run(self, test, compileflags=None, out=None, clear_globs=True):
 
         # Hack: ipython needs access to the execution context of the example,
         # so that it can propagate user variables loaded by %run into
         # test.globs.  We put them here into our modified %run as a function
         # attribute.  Our new %run will then only make the namespace update
         # when called (rather than unconconditionally updating test.globs here
         # for all examples, most of which won't be calling %run anyway).
         _run_ns_sync.test_globs = test.globs
 
         return super(IPDocTestRunner,self).run(test,
                                                compileflags,out,clear_globs)
 
 
 class DocFileCase(doctest.DocFileCase):
     """Overrides to provide filename
     """
     def address(self):
         return (self._dt_test.filename, None, None)
 
 
 class ExtensionDoctest(doctests.Doctest):
     """Nose Plugin that supports doctests in extension modules.
     """
     name = 'extdoctest'   # call nosetests with --with-extdoctest
     enabled = True
 
     def options(self, parser, env=os.environ):
         Plugin.options(self, parser, env)
+        parser.add_option('--doctest-tests', action='store_true',
+                          dest='doctest_tests',
+                          default=env.get('NOSE_DOCTEST_TESTS',True),
+                          help="Also look for doctests in test modules. "
+                          "Note that classes, methods and functions should "
+                          "have either doctests or non-doctest tests, "
+                          "not both. [NOSE_DOCTEST_TESTS]")
+        parser.add_option('--doctest-extension', action="append",
+                          dest="doctestExtension",
+                          help="Also look for doctests in files with "
+                          "this extension [NOSE_DOCTEST_EXTENSION]")
+        # Set the default as a list, if given in env; otherwise
+        # an additional value set on the command line will cause
+        # an error.
+        env_setting = env.get('NOSE_DOCTEST_EXTENSION')
+        if env_setting is not None:
+            parser.set_defaults(doctestExtension=tolist(env_setting))
+
 
     def configure(self, options, config):
         Plugin.configure(self, options, config)
         self.doctest_tests = options.doctest_tests
         self.extension = tolist(options.doctestExtension)
 
         self.parser = doctest.DocTestParser()
         self.finder = DocTestFinder()
         self.checker = IPDoctestOutputChecker()
         self.globs = None
         self.extraglobs = None
 
     def loadTestsFromExtensionModule(self,filename):
         bpath,mod = os.path.split(filename)
         modname = os.path.splitext(mod)[0]
         try:
             sys.path.append(bpath)
             module = __import__(modname)
             tests = list(self.loadTestsFromModule(module))
         finally:
             sys.path.pop()
         return tests
 
     # NOTE: the method below is almost a copy of the original one in nose, with
     # a  few modifications to control output checking.
 
     def loadTestsFromModule(self, module):
         #print 'lTM',module  # dbg
 
         if not self.matches(module.__name__):
             log.debug("Doctest doesn't want module %s", module)
             return
 
         tests = self.finder.find(module,globs=self.globs,
                                  extraglobs=self.extraglobs)
         if not tests:
             return
 
         # always use whitespace and ellipsis options
         optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
 
         tests.sort()
         module_file = module.__file__
         if module_file[-4:] in ('.pyc', '.pyo'):
             module_file = module_file[:-1]
         for test in tests:
             if not test.examples:
                 continue
             if not test.filename:
                 test.filename = module_file
             
             yield DocTestCase(test,
                               optionflags=optionflags,
                               checker=self.checker)
 
 
     def loadTestsFromFile(self, filename):
         #print 'lTF',filename  # dbg
 
         if is_extension_module(filename):
             for t in self.loadTestsFromExtensionModule(filename):
                 yield t
         else:
             if self.extension and anyp(filename.endswith, self.extension):
                 name = os.path.basename(filename)
                 dh = open(filename)
                 try:
                     doc = dh.read()
                 finally:
                     dh.close()
                 test = self.parser.get_doctest(
                     doc, globs={'__file__': filename}, name=name,
                     filename=filename, lineno=0)
                 if test.examples:
                     #print 'FileCase:',test.examples  # dbg
                     yield DocFileCase(test)
                 else:
                     yield False # no tests to load
 
     def wantFile(self,filename):
         """Return whether the given filename should be scanned for tests.
 
         Modified version that accepts extension modules as valid containers for
         doctests.
         """
-        #print 'Filename:',filename  # dbg
+        print 'Filename:',filename  # dbg
 
         # XXX - temporarily hardcoded list, will move to driver later
         exclude = ['IPython/external/',
-                   'IPython/Extensions/ipy_',
                    'IPython/platutils_win32',
                    'IPython/frontend/cocoa',
                    'IPython_doctest_plugin',
                    'IPython/Gnuplot',
-                   'IPython/Extensions/PhysicalQIn']
+                   'IPython/Extensions/ipy_',
+                   'IPython/Extensions/PhysicalQIn',
+                   'IPython/Extensions/scitedirector',
+                   'IPython/testing/plugin',
+                   ]
 
         for fex in exclude:
             if fex in filename:  # substring
                 #print '###>>> SKIP:',filename  # dbg
                 return False
 
         if is_extension_module(filename):
             return True
         else:
             return doctests.Doctest.wantFile(self,filename)
 
 
 class IPythonDoctest(ExtensionDoctest):
     """Nose Plugin that supports doctests in extension modules.
     """
     name = 'ipdoctest'   # call nosetests with --with-ipdoctest
     enabled = True
 
     def configure(self, options, config):
 
         Plugin.configure(self, options, config)
         self.doctest_tests = options.doctest_tests
         self.extension = tolist(options.doctestExtension)
 
         self.parser = IPDocTestParser()
         self.finder = DocTestFinder(parser=self.parser)
         self.checker = IPDoctestOutputChecker()
         self.globs = None
         self.extraglobs = None
+

IPython/testing/plugin/test_refs.py

@@ -1,180 +1,51
+"""Some simple tests for the plugin while running scripts.
+"""
 # Module imports
 # Std lib
 import inspect
 
-# Third party
-
 # Our own
 from IPython.testing import decorators as dec
 
 #-----------------------------------------------------------------------------
-# Utilities
-
-# Note: copied from OInspect, kept here so the testing stuff doesn't create
-# circular dependencies and is easier to reuse.
-def getargspec(obj):
-    """Get the names and default values of a function's arguments.
-
-    A tuple of four things is returned: (args, varargs, varkw, defaults).
-    'args' is a list of the argument names (it may contain nested lists).
-    'varargs' and 'varkw' are the names of the * and ** arguments or None.
-    'defaults' is an n-tuple of the default values of the last n arguments.
-
-    Modified version of inspect.getargspec from the Python Standard
-    Library."""
-
-    if inspect.isfunction(obj):
-        func_obj = obj
-    elif inspect.ismethod(obj):
-        func_obj = obj.im_func
-    else:
-        raise TypeError, 'arg is not a Python function'
-    args, varargs, varkw = inspect.getargs(func_obj.func_code)
-    return args, varargs, varkw, func_obj.func_defaults
-
-#-----------------------------------------------------------------------------
 # Testing functions
 
 def test_trivial():
     """A trivial passing test."""
     pass
 
-
[e-mail]
-def test_deliberately_broken():
-    """A deliberately broken test - we want to skip this one."""
-    1/0
-
-
-# Verify that we can correctly skip the doctest for a function at will, but
-# that the docstring itself is NOT destroyed by the decorator.
[e-mail]_doctest
-def doctest_bad(x,y=1,**k):
-    """A function whose doctest we need to skip.
-
-    >>> 1+1
-    3
-    """
-    print 'x:',x
-    print 'y:',y
-    print 'k:',k
-
-
-def call_doctest_bad():
-    """Check that we can still call the decorated functions.
-    
-    >>> doctest_bad(3,y=4)
-    x: 3
-    y: 4
-    k: {}
-    """
-    pass
-
-
-# Doctest skipping should work for class methods too
-class foo(object):
-    """Foo
-
-    Example:
-
-    >>> 1+1
-    2
-    """
-
-    @dec.skip_doctest
-    def __init__(self,x):
-        """Make a foo.
-
-        Example:
-
-        >>> f = foo(3)
-        junk
-        """
-        print 'Making a foo.'
-        self.x = x
-        
-    @dec.skip_doctest
-    def bar(self,y):
-        """Example:
-
-        >>> f = foo(3)
-        >>> f.bar(0)
-        boom!
-        >>> 1/0
-        bam!
-        """
-        return 1/y
-
-    def baz(self,y):
-        """Example:
-
-        >>> f = foo(3)
-        Making a foo.
-        >>> f.baz(3)
-        True
-        """
-        return self.x==y
-
-
-def test_skip_dt_decorator():
-    """Doctest-skipping decorator should preserve the docstring.
-    """
-    # Careful: 'check' must be a *verbatim* copy of the doctest_bad docstring!
-    check = """A function whose doctest we need to skip.
-
-    >>> 1+1
-    3
-    """
-    # Fetch the docstring from doctest_bad after decoration.
-    val = doctest_bad.__doc__
-    
-    assert check==val,"doctest_bad docstrings don't match"
-
-
-def test_skip_dt_decorator2():
-    """Doctest-skipping decorator should preserve function signature.
-    """
-    # Hardcoded correct answer
-    dtargs = (['x', 'y'], None, 'k', (1,))
-    # Introspect out the value
-    dtargsr = getargspec(doctest_bad)
-    assert dtargsr==dtargs, \
-           "Incorrectly reconstructed args for doctest_bad: %s" % (dtargsr,)
-
-
 def doctest_run():
     """Test running a trivial script.
 
     In [13]: run simplevars.py
     x is: 1
     """
     
-#@dec.skip_doctest
 def doctest_runvars():
     """Test that variables defined in scripts get loaded correcly via %run.
 
     In [13]: run simplevars.py
     x is: 1
 
     In [14]: x
     Out[14]: 1
     """
 
 def doctest_ivars():
     """Test that variables defined interactively are picked up.
     In [5]: zz=1
 
     In [6]: zz
     Out[6]: 1
     """
     
 @dec.skip_doctest
 def doctest_refs():
     """DocTest reference holding issues when running scripts.
 
     In [32]: run show_refs.py
     c referrers: [<type 'dict'>]
 
     In [33]: map(type,gc.get_referrers(c))
     Out[33]: [<type 'dict'>]
     """

IPython/testing/tutils.py

@@ -1,86 +1,87
 """DEPRECATED - use IPython.testing.util instead.
 
 Utilities for testing code.
 """
 
 #############################################################################
 
 # This was old testing code we never really used in IPython.  The pieces of
 # testing machinery from snakeoil that were good have already been merged into
 # the nose plugin, so this can be taken away soon.  Leave a warning for now,
 # we'll remove it in a later release (around 0.10 or so).
+
 from warnings import warn
 warn('This will be removed soon.  Use IPython.testing.util instead',
      DeprecationWarning)
 
 #############################################################################
 
 # Required modules and packages
 
 # Standard Python lib
 import os
 import sys
 
 # From this project
 from IPython.tools import utils
 
 # path to our own installation, so we can find source files under this.
 TEST_PATH = os.path.dirname(os.path.abspath(__file__))
 
 # Global flag, used by vprint
 VERBOSE = '-v' in sys.argv or '--verbose' in sys.argv
 
 ##########################################################################
 # Code begins
 
 # Some utility functions
 def vprint(*args):
     """Print-like function which relies on a global VERBOSE flag."""
     if not VERBOSE:
         return
 
     write = sys.stdout.write
     for item in args:
         write(str(item))
     write('\n')
     sys.stdout.flush()
 
 def test_path(path):
     """Return a path as a subdir of the test package.
 
     This finds the correct path of the test package on disk, and prepends it
     to the input path."""
 
     return os.path.join(TEST_PATH,path)
 
 def fullPath(startPath,files):
     """Make full paths for all the listed files, based on startPath.
 
     Only the base part of startPath is kept, since this routine is typically
     used with a script's __file__ variable as startPath.  The base of startPath
     is then prepended to all the listed files, forming the output list.
 
     :Parameters:
       startPath : string
         Initial path to use as the base for the results.  This path is split
       using os.path.split() and only its first component is kept.
 
       files : string or list
         One or more files.
 
     :Examples:
 
     >>> fullPath('/foo/bar.py',['a.txt','b.txt'])
     ['/foo/a.txt', '/foo/b.txt']
 
     >>> fullPath('/foo',['a.txt','b.txt'])
     ['/a.txt', '/b.txt']
 
     If a single file is given, the output is still a list:
     >>> fullPath('/foo','a.txt')
     ['/a.txt']
     """
 
     files = utils.list_strings(files)
     base = os.path.split(startPath)[0]
     return [ os.path.join(base,f) for f in files ]

IPython/ultraTB.py

@@ -1,1059 +1,1062
 # -*- 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.
 
 $Id: ultraTB.py 2908 2007-12-30 21:07:46Z vivainio $"""
 
 #*****************************************************************************
 #       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 IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % (Release.authors['Nathan']+
                                     Release.authors['Fernando'])
 __license__ = Release.license
 
 # Required modules
 import inspect
 import keyword
 import linecache
 import os
 import pydoc
 import re
 import string
 import sys
 import time
 import tokenize
 import traceback
 import types
 
 # 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 import Debugger, PyColorize
 from IPython.ipstruct import Struct
 from IPython.excolors import ExceptionColors
 from IPython.genutils import Term,uniq_stable,error,info
 
 # 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')
 
 
 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 py25
 if sys.version_info[:2] >= (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):
     import linecache
     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 = linecache.getlines(file)[start:end]
         # pad with empty lines if necessary
         if maybeStart < 0:
             lines = (['\n'] * -maybeStart) + lines
         if len(lines) < context:
             lines += ['\n'] * (context - len(lines))
         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 _formatTracebackLines(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:
         try:
             scheme = __IPYTHON__.rc.colors
         except:
             scheme = DEFAULT_SCHEME
     _line_format = _parser.format2
 
     for line in lines:
         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:
     """Basic tools used by all traceback printer classes."""
 
     def __init__(self,color_scheme = 'NoColor',call_pdb=False):
         # Whether to call the interactive pdb debugger after printing
         # tracebacks or not
         self.call_pdb = call_pdb
 
         # Create color table
         self.color_scheme_table = ExceptionColors 
 
         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 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
 
 #---------------------------------------------------------------------------
 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'):
         TBTools.__init__(self,color_scheme = color_scheme,call_pdb=0)
         
     def __call__(self, etype, value, elist):
         Term.cout.flush()
         print >> Term.cerr, self.text(etype,value,elist)
         Term.cerr.flush()
 
     def text(self,etype, value, elist,context=5):
         """Return a color formatted string with the traceback info."""
 
         Colors = self.Colors
         out_string = ['%s%s%s\n' % (Colors.topline,'-'*60,Colors.Normal)]
         if elist:
             out_string.append('Traceback %s(most recent call last)%s:' % \
                                 (Colors.normalEm, Colors.Normal) + '\n')
             out_string.extend(self._format_list(elist))
         lines = self._format_exception_only(etype, value)
         for line in lines[:-1]:
             out_string.append(" "+line)
         out_string.append(lines[-1])
         return ''.join(out_string)
 
     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 = 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 = item + '%s    %s%s\n' % (Colors.line, line.strip(),
                                             Colors.Normal)
         list.append(item)
         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 = []
         try:
             stype = Colors.excName + etype.__name__ + Colors.Normal
         except AttributeError:
             stype = etype  # String exceptions don't get special coloring
         if value is None:
             list.append( str(stype) + '\n')
         else:
             if etype is SyntaxError:
                 try:
                     msg, (filename, lineno, offset, line) = value
                 except:
-                    pass
+                    have_filedata = False
                 else:
+                    have_filedata = True
                     #print 'filename is',filename  # dbg
                     if not filename: filename = "<string>"
                     list.append('%s  File %s"%s"%s, line %s%d%s\n' % \
                             (Colors.normalEm,
                              Colors.filenameEm, filename, Colors.normalEm,
                              Colors.linenoEm, lineno, Colors.Normal  ))
                     if line is not None:
                         i = 0
                         while i < len(line) and line[i].isspace():
                             i = i+1
                         list.append('%s    %s%s\n' % (Colors.line,
                                                       line.strip(), 
                                                       Colors.Normal))
                         if offset is not None:
                             s = '    '
                             for c in line[i:offset-1]:
                                 if c.isspace():
                                     s = s + c
                                 else:
                                     s = s + ' '
                             list.append('%s%s^%s\n' % (Colors.caret, s,
                                                        Colors.Normal) )
                         value = msg
             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))
 
         # vds:>>
-        __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
+        if have_filedata:
+            __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
         # vds:<<
 
         return list
 
     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',tb_offset=0,long_header=0,
                  call_pdb = 0, include_vars=1):
         """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)
         self.tb_offset = tb_offset
         self.long_header = long_header
         self.include_vars = include_vars
 
     def text(self, etype, evalue, etb, context=5):
         """Return a nice text document describing the traceback."""
 
         # 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 ' + string.split(sys.version)[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, string.rjust(date, 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,
                                      string.rjust('Traceback (most recent call last)',
                                                   75 - len(str(etype)) ) )
         frames = []
         # Flush cache before calling inspect.  This helps alleviate some of the
         # problems with python 2.3's inspect.py.
         linecache.checkcache()
         # 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)[self.tb_offset:]
             #print 'python records:', records # dbg
             records = _fixed_getinnerframes(etb, context,self.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=Term.cerr)
             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
             try:
                 file = file and abspath(file) or '?'
             except OSError:
                 # if file is '<console>' or something not in the filesystem,
                 # the abspath call will throw an OSError.  Just ignore it and
                 # keep the original file string.
                 pass
             link = tpl_link % file
             try:
                 args, varargs, varkw, locals = inspect.getargvalues(frame)
             except:
                 # This can happen due to a bug in python2.3.  We should be
                 # able to remove this try/except when 2.4 becomes a
                 # requirement.  Bug details at http://python.org/sf/1005466
                 inspect_error()
                 traceback.print_exc(file=Term.cerr)
                 info("\nIPython's exception reporting continues...\n")
                 
             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:
                     # Very odd crash from inspect.formatargvalues().  The
                     # scenario under which it appeared was a call to
                     # view(array,scale) in NumTut.view.view(), where scale had
                     # been defined as a scalar (it should be a tuple). Somehow
                     # inspect messes up resolving the argument list of view()
                     # and barfs out. At some point I should dig into this one
                     # and file a bug report about it.
                     inspect_error()
                     traceback.print_exc(file=Term.cerr)
                     info("\nIPython's exception reporting continues...\n")
                     call = tpl_call_fail % func
 
             # Initialize a list of names on the current line, which the
             # tokenizer below will populate.
             names = []
 
             def tokeneater(token_type, token, start, end, line):
                 """Stateful tokeneater which builds dotted names.
 
                 The list of names it appends to (from the enclosing scope) can
                 contain repeated composite names.  This is unavoidable, since
                 there is no way to disambguate partial dotted structures until
                 the full list is known.  The caller is responsible for pruning
                 the final list of duplicates before using it."""
                 
                 # build composite names
                 if token == '.':
                     try:
                         names[-1] += '.'
                         # store state so the next token is added for x.y.z names
                         tokeneater.name_cont = True
                         return
                     except IndexError:
                         pass
                 if token_type == tokenize.NAME and token not in keyword.kwlist:
                     if tokeneater.name_cont:
                         # Dotted names
                         names[-1] += token
                         tokeneater.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_type == tokenize.NEWLINE:
                     raise IndexError
             # we need to store a bit of state in the tokenizer to build
             # dotted names
             tokeneater.name_cont = False
 
             def linereader(file=file, lnum=[lnum], getline=linecache.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:
                 # This builds the names list in-place by capturing it from the
                 # enclosing scope.
                 tokenize.tokenize(linereader, tokeneater)
             except IndexError:
                 # signals exit of tokenizer
                 pass
             except tokenize.TokenError,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)
             
             # 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 locals.has_key(name_base):
                             try:
                                 value = repr(eval(name_full,locals))
                             except:
                                 value = undefined
                         else:
                             value = undefined
                         name = tpl_local_var % name_full
                     else:
                         if frame.f_globals.has_key(name_base):
                             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(
                     _formatTracebackLines(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, evalue_str)]
         if 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, 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:
-             frame, file, lnum, func, lines, index = records[-1]
-             #print "file:", str(file), "linenb", str(lnum)         
-             file = abspath(file)
-             __IPYTHON__.hooks.synchronize_with_editor(file, lnum, 0)
+             filepath, lnum = records[-1][1:3]
+             #print "file:", str(file), "linenb", str(lnum) # dbg
+             filepath = os.path.abspath(filepath)
+             __IPYTHON__.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]) )
 
     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
             dhook = sys.displayhook
             sys.displayhook = sys.__displayhook__
             self.pdb.reset()
             # Find the right frame so we don't pop up inside ipython itself
             if hasattr(self,'tb'):
                 etb = self.tb
             else:
                 etb = self.tb = sys.last_traceback
             while self.tb.tb_next is not None:
                 self.tb = self.tb.tb_next
             try:
                 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)
             finally:
                 sys.displayhook = dhook
             
         if hasattr(self,'tb'):
             del self.tb
 
     def handler(self, info=None):
         (etype, evalue, etb) = info or sys.exc_info()
         self.tb = etb
         Term.cout.flush()
         print >> Term.cerr, self.text(etype, evalue, etb)
         Term.cerr.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',
                  tb_offset = 0,long_header=0,call_pdb=0,include_vars=0):
 
         # 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,tb_offset,long_header,
                            call_pdb=call_pdb,include_vars=include_vars)
         self.set_mode(mode)
         
     def _extract_tb(self,tb):
         if tb:
             return traceback.extract_tb(tb)
         else:
             return None
 
     def text(self, etype, value, tb,context=5,mode=None):
         """Return formatted traceback.
 
         If the optional mode parameter is given, it overrides the current
         mode."""
 
         if mode is None:
             mode = self.mode
         if mode in self.verbose_modes:
             # verbose modes need a full traceback
             return VerboseTB.text(self,etype, value, tb,context=5)
         else:
             # We must check the source cache because otherwise we can print
             # out-of-date source code.
             linecache.checkcache()
             # Now we can extract and format the exception
             elist = self._extract_tb(tb)
             if len(elist) > self.tb_offset:
                 del elist[:self.tb_offset]
             return ListTB.text(self,etype,value,elist)
 
     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])
 
     # 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 = Term.cerr
         Term.cout.flush()
         if tb_offset is not None:
             tb_offset, self.tb_offset = self.tb_offset, tb_offset
             print >> out, self.text(etype, evalue, etb)
             self.tb_offset = tb_offset
         else:
             print >> out, self.text(etype, evalue, etb)
         out.flush()
         try:
             self.debugger()
         except KeyboardInterrupt:
             print "\nKeyboardInterrupt"
 
     def text(self,etype=None,value=None,tb=None,context=5,mode=None):
         if etype is None:
             etype,value,tb = sys.exc_info()
         self.tb = tb
         return FormattedTB.text(self,etype,value,tb,context=5,mode=mode)
 
 #---------------------------------------------------------------------------
 # 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)
 
 #----------------------------------------------------------------------------
 # module testing (minimal)
 if __name__ == "__main__":
     def spam(c, (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:
         apply(handler, sys.exc_info() )
     print ''
     
     handler = VerboseTB()
     print '*** VerboseTB ***'
     try:
         print spam(1, (2, 3))
     except:
         apply(handler, sys.exc_info() )
     print ''
     

MANIFEST.in

@@ -1,32 +1,32
-include README_Windows.txt
-include win32_manual_post_install.py
 include ipython.py
 include setupbase.py
+include setupegg.py
 
 graft scripts
 
 graft setupext
 
 graft IPython/UserConfig
 
 graft IPython/kernel
 graft IPython/config
 graft IPython/testing
 graft IPython/tools
 
 recursive-include IPython/Extensions igrid_help*
 
 graft docs
 exclude docs/\#*
 exclude docs/man/*.1
 
 # docs subdirs we want to skip
 prune docs/attic
 prune docs/build
 
 global-exclude *~
 global-exclude *.flc
 global-exclude *.pyc
 global-exclude .dircopy.log
 global-exclude .svn
 global-exclude .bzr
+global-exclude .hgignore

README.txt

@@ -1,11 +1,11
-===============
-IPython1 README
-===============
- 
-.. contents::
+==============
+IPython README
+==============
 
 Overview
 ========
 
-Welcome to IPython.  New users should consult our documentation, which can be found
-in the docs/source subdirectory.
+Welcome to IPython. Our documentation can be found in the docs/source
+subdirectory. We also have ``.html`` and ``.pdf`` versions of this
+documentation available on the IPython `website <http://ipython.scipy.org>`_.
+

docs/Makefile

@@ -1,87 +1,86
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
 	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
 
 clean:
-	-rm -rf build/*
+	-rm -rf build/* dist/*
 
 pdf: latex
 	cd build/latex && make all-pdf
 
 all: html pdf
 
-dist: all
+dist: clean all
 	mkdir -p dist
-	-rm -rf dist/*
-	ln build/latex/IPython.pdf dist/
+	ln build/latex/ipython.pdf dist/
 	cp -al build/html dist/
 	@echo "Build finished.  Final docs are in dist/"
 
 html:
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files or run"
 	@echo "  sphinx-web build/pickle"
 	@echo "to start the sphinx-web server."
 
 web: pickle
 
 htmlhelp:
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
 latex:
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
 	mkdir -p build/changes build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
 
 linkcheck:
 	mkdir -p build/linkcheck build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.txt."

docs/examples/kernel/mcpricer.py

@@ -1,42 +1,43
 import numpy as N
 from math import *
 
 class MCOptionPricer(object):
     def __init__(self, S=100.0, K=100.0, sigma=0.25, r=0.05, days=260, paths=10000):
         self.S = S
         self.K = K
         self.sigma = sigma
         self.r = r
         self.days = days
         self.paths = paths
         self.h = 1.0/self.days
         self.const1 = exp((self.r-0.5*self.sigma**2)*self.h)
         self.const2 = self.sigma*sqrt(self.h)
         
     def run(self):
         stock_price = self.S*N.ones(self.paths, dtype='float64')
         stock_price_sum = N.zeros(self.paths, dtype='float64')
         for j in range(self.days):
             growth_factor = self.const1*N.exp(self.const2*N.random.standard_normal(self.paths))
             stock_price = stock_price*growth_factor
             stock_price_sum = stock_price_sum + stock_price
         stock_price_avg = stock_price_sum/self.days
         zeros = N.zeros(self.paths, dtype='float64')
         r_factor = exp(-self.r*self.h*self.days)
         self.vanilla_put = r_factor*N.mean(N.maximum(zeros,self.K-stock_price))
         self.asian_put = r_factor*N.mean(N.maximum(zeros,self.K-stock_price_avg))
         self.vanilla_call = r_factor*N.mean(N.maximum(zeros,stock_price-self.K))
         self.asian_call = r_factor*N.mean(N.maximum(zeros,stock_price_avg-self.K))
 
 
 def main():
     op = MCOptionPricer()
     op.run()
     print "Vanilla Put Price = ", op.vanilla_put
     print "Asian Put Price = ", op.asian_put
     print "Vanilla Call Price = ", op.vanilla_call
     print "Asian Call Price = ", op.asian_call
 
 
 if __name__ == '__main__':
     main()
+

docs/examples/kernel/nwmerge.py

@@ -1,120 +1,123
 """Example showing how to merge multiple remote data streams.
 """
 # Slightly modified version of:
 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/511509
 
 import heapq
 from IPython.kernel.error import CompositeError
 
 def mergesort(list_of_lists, key=None):
     """ Perform an N-way merge operation on sorted lists.
 
     @param list_of_lists: (really iterable of iterable) of sorted elements
     (either by naturally or by C{key})
     @param key: specify sort key function (like C{sort()}, C{sorted()})
 
     Yields tuples of the form C{(item, iterator)}, where the iterator is the
     built-in list iterator or something you pass in, if you pre-generate the
     iterators.
 
     This is a stable merge; complexity O(N lg N)
 
     Examples::
 
     >>> print list(mergesort([[1,2,3,4],
     ...                      [2,3.25,3.75,4.5,6,7],
     ...                      [2.625,3.625,6.625,9]]))
     [1, 2, 2, 2.625, 3, 3.25, 3.625, 3.75, 4, 4.5, 6, 6.625, 7, 9]
 
     # note stability
     >>> print list(mergesort([[1,2,3,4],
     ...                      [2,3.25,3.75,4.5,6,7],
     ...                      [2.625,3.625,6.625,9]],
     ...                      key=int))
     [1, 2, 2, 2.625, 3, 3.25, 3.75, 3.625, 4, 4.5, 6, 6.625, 7, 9]
 
 
     >>> print list(mergesort([[4, 3, 2, 1],
     ...                      [7, 6, 4.5, 3.75, 3.25, 2],
     ...                      [9, 6.625, 3.625, 2.625]],
     ...                      key=lambda x: -x))
     [9, 7, 6.625, 6, 4.5, 4, 3.75, 3.625, 3.25, 3, 2.625, 2, 2, 1]
     """
 
     heap = []
     for i, itr in enumerate(iter(pl) for pl in list_of_lists):
         try:
             item = itr.next()
-            toadd = (key(item), i, item, itr) if key else (item, i, itr)
+            if key:
+                toadd = (key(item), i, item, itr)
+            else:
+                toadd = (item, i, itr)
             heap.append(toadd)
         except StopIteration:
             pass
     heapq.heapify(heap)
 
     if key:
         while heap:
             _, idx, item, itr = heap[0]
             yield item
             try:
                 item = itr.next()
                 heapq.heapreplace(heap, (key(item), idx, item, itr) )
             except StopIteration:
                 heapq.heappop(heap)
 
     else:
         while heap:
             item, idx, itr = heap[0]
             yield item
             try:
                 heapq.heapreplace(heap, (itr.next(), idx, itr))
             except StopIteration:
                 heapq.heappop(heap)
 
 
 def remote_iterator(rc,engine,name):
     """Return an iterator on an object living on a remote engine.
     """
     # Check that the object exists on the engine and pin a reference to it
     iter_name = '_%s_rmt_iter_' % name
     rc.execute('%s = iter(%s)' % (iter_name,name), targets=engine)
     tpl = '_tmp = %s.next()' % iter_name
     while True:
         try:
             rc.execute(tpl, targets=engine)
             result = rc.pull('_tmp', targets=engine)[0]
         # This causes the StopIteration exception to be raised.
         except CompositeError, e:
             e.raise_exception()
         else:
             yield result
 
 # Main, interactive testing
 if __name__ == '__main__':
 
     from IPython.kernel import client
     ipc = client.MultiEngineClient()
     print 'Engine IDs:',ipc.get_ids()
 
     # Make a set of 'sorted datasets'
     a0 = range(5,20)
     a1 = range(10)
     a2 = range(15,25)
 
     # Now, imagine these had been created in the remote engines by some long
     # computation.  In this simple example, we just send them over into the
     # remote engines.  They will all be called 'a' in each engine.
     ipc.push(dict(a=a0), targets=0)
     ipc.push(dict(a=a1), targets=1)
     ipc.push(dict(a=a2), targets=2)
 
     # And we now make a local object which represents the remote iterator
     aa0 = remote_iterator(ipc,0,'a')
     aa1 = remote_iterator(ipc,1,'a')
     aa2 = remote_iterator(ipc,2,'a')
 
     # Let's merge them, both locally and remotely:
     print 'Merge the local datasets:'
     print list(mergesort([a0,a1,a2]))
     
     print 'Locally merge the remote sets:'
     print list(mergesort([aa0,aa1,aa2]))

docs/examples/kernel/rmt.ipy

@@ -1,57 +1,57
 #-------------------------------------------------------------------------------
 # Driver code that the client runs.
 #-------------------------------------------------------------------------------
 # To run this code start a controller and engines using:
 # ipcluster -n 2
 # Then run the scripts by doing irunner rmt.ipy or by starting ipython and
 # doing run rmt.ipy.
 
 from rmtkernel import *
 from IPython.kernel import client
 
 
 def wignerDistribution(s):
     """Returns (s, rho(s)) for the Wigner GOE distribution."""
     return (numpy.pi*s/2.0) * numpy.exp(-numpy.pi*s**2/4.)
 
 
 def generateWignerData():
     s = numpy.linspace(0.0,4.0,400)
     rhos = wignerDistribution(s)
     return s, rhos
     
 
 def serialDiffs(num, N):
     diffs = ensembleDiffs(num, N)
     normalizedDiffs = normalizeDiffs(diffs)
     return normalizedDiffs
 
 
 def parallelDiffs(rc, num, N):
     nengines = len(rc.get_ids())
     num_per_engine = num/nengines
     print "Running with", num_per_engine, "per engine."
     rc.push(dict(num_per_engine=num_per_engine, N=N))
     rc.execute('diffs = ensembleDiffs(num_per_engine, N)')
 	# gather blocks always for now
     pr = rc.gather('diffs')
     return pr.r
 
 
 # Main code
 if __name__ == '__main__':
     rc = client.MultiEngineClient()
     print "Distributing code to engines..."
     r = rc.run('rmtkernel.py')
     rc.block = False
 
     # Simulation parameters
     nmats = 100
     matsize = 30
     
     %timeit -n1 -r1 serialDiffs(nmats,matsize)
     %timeit -n1 -r1 parallelDiffs(rc, nmats, matsize)
 
     # Uncomment these to plot the histogram
-    import pylab
-    pylab.hist(parallelDiffs(rc,matsize,matsize))
+    # import pylab
+    # pylab.hist(parallelDiffs(rc,matsize,matsize))

docs/source/changes.txt

@@ -1,200 +1,393
 .. _changes:
 
 ==========
 What's new
 ==========
 
 .. contents::
+..
+    1  Release 0.9.1
+    2  Release 0.9
+      2.1  New features
+      2.2  Bug fixes
+      2.3  Backwards incompatible changes
+      2.4  Changes merged in from IPython1
+        2.4.1  New features
+        2.4.2  Bug fixes
+        2.4.3  Backwards incompatible changes
+    3  Release 0.8.4
+    4  Release 0.8.3
+    5  Release 0.8.2
+    6  Older releases
+..
+
+Release dev
+===========
+
+New features
+------------
+
+* The wonderful TextMate editor can now be used with %edit on OS X.  Thanks
+  to Matt Foster for this patch.
+
+* Fully refactored :command:`ipcluster` command line program for starting
+  IPython clusters.  This new version is a complete rewrite and 1) is fully
+  cross platform (we now use Twisted's process management), 2) has much
+  improved performance, 3) uses subcommands for different types of clusters, 
+  4) uses argparse for parsing command line options, 5) has better support
+  for starting clusters using :command:`mpirun`, 6) has experimental support
+  for starting engines using PBS.  However, this new version of ipcluster
+  should be considered a technology preview.  We plan on changing the API
+  in significant ways before it is final.
+
+* The :mod:`argparse` module has been added to :mod:`IPython.external`.
+
+* Fully description of the security model added to the docs.
+
+* cd completer: show bookmarks if no other completions are available.
+
+* sh profile: easy way to give 'title' to prompt: assign to variable
+  '_prompt_title'. It looks like this::
+      
+        [~]|1> _prompt_title = 'sudo!'
+        sudo![~]|2>
+
+* %edit: If you do '%edit pasted_block', pasted_block
+  variable gets updated with new data (so repeated 
+  editing makes sense)
+
+Bug fixes
+---------
+
+* The ipengine and ipcontroller scripts now handle missing furl files
+  more gracefully by giving better error messages.
+
+* %rehashx: Aliases no longer contain dots. python3.0 binary
+  will create alias python30. Fixes:
+  #259716 "commands with dots in them don't work"
+
+* %cpaste: %cpaste -r repeats the last pasted block.
+  The block is assigned to pasted_block even if code
+  raises exception.
+
+Backwards incompatible changes
+------------------------------
+
+* The controller now has a ``-r`` flag that needs to be used if you want to
+  reuse existing furl files.  Otherwise they are deleted (the default).
+
+* Remove ipy_leo.py. "easy_install ipython-extension" to get it.
+  (done to decouple it from ipython release cycle)
+
+
+
+Release 0.9.1
+=============
+
+This release was quickly made to restore compatibility with Python 2.4, which
+version 0.9 accidentally broke.  No new features were introduced, other than
+some additional testing support for internal use.
+
 
 Release 0.9
 ===========
 
 New features
 ------------
 
-	* The notion of a task has been completely reworked.  An `ITask` interface has
-	  been created.  This interface defines the methods that tasks need to implement.
-	  These methods are now responsible for things like submitting tasks and processing
-	  results.  There are two basic task types: :class:`IPython.kernel.task.StringTask`
-	  (this is the old `Task` object, but renamed) and the new 
-	  :class:`IPython.kernel.task.MapTask`, which is based on a function.
-	* A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to
-	  standardize the idea of a `map` method.  This interface has a single
-	  `map` method that has the same syntax as the built-in `map`.  We have also defined
-	  a `mapper` factory interface that creates objects that implement
-	  :class:`IPython.kernel.mapper.IMapper` for different controllers.  Both
-	  the multiengine and task controller now have mapping capabilties.
-	* The parallel function capabilities have been reworks.  The major changes are that
-	  i) there is now an `@parallel` magic that creates parallel functions, ii)
-	  the syntax for mulitple variable follows that of `map`, iii) both the
-	  multiengine and task controller now have a parallel function implementation.
-	* All of the parallel computing capabilities from `ipython1-dev` have been merged into
-	  IPython proper.  This resulted in the following new subpackages:  
-	  :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
-	  :mod:`IPython.tools` and :mod:`IPython.testing`.
-	* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and friends
-	  have been completely refactored.  Now we are checking for dependencies using
-	  the approach that matplotlib uses.
-	* The documentation has been completely reorganized to accept the documentation
-	  from `ipython1-dev`.
-	* We have switched to using Foolscap for all of our network protocols in
-	  :mod:`IPython.kernel`.  This gives us secure connections that are both encrypted
-	  and authenticated.
-	* We have a brand new `COPYING.txt` files that describes the IPython license
-	  and copyright.  The biggest change is that we are putting "The IPython
-	  Development Team" as the copyright holder.  We give more details about exactly
-	  what this means in this file.  All developer should read this and use the new
-	  banner in all IPython source code files.
-	* sh profile: ./foo runs foo as system command, no need to do !./foo anymore
-	* String lists now support 'sort(field, nums = True)' method (to easily
-	  sort system command output). Try it with 'a = !ls -l ; a.sort(1, nums=1)'
-	* '%cpaste foo' now assigns the pasted block as string list, instead of string
-	* The ipcluster script now run by default with no security.  This is done because
-	  the main usage of the script is for starting things on localhost.  Eventually
-	  when ipcluster is able to start things on other hosts, we will put security
-	  back.
-	* 'cd --foo' searches directory history for string foo, and jumps to that dir.
-	  Last part of dir name is checked first. If no matches for that are found,
-	  look at the whole path.
+* All furl files and security certificates are now put in a read-only
+  directory named ~./ipython/security.
+
+* A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that
+  determines the user's IPython directory in a robust manner.
+
+* Laurent's WX application has been given a top-level script called
+  ipython-wx, and it has received numerous fixes. We expect this code to be
+  architecturally better integrated with Gael's WX 'ipython widget' over the
+  next few releases.
+
+* The Editor synchronization work by Vivian De Smedt has been merged in.  This
+  code adds a number of new editor hooks to synchronize with editors under
+  Windows.
+
+* A new, still experimental but highly functional, WX shell by Gael Varoquaux.
+  This work was sponsored by Enthought, and while it's still very new, it is
+  based on a more cleanly organized arhictecture of the various IPython
+  components. We will continue to develop this over the next few releases as a
+  model for GUI components that use IPython.
+
+* Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework),
+  authored by Barry Wark.  Currently the WX and the Cocoa ones have slightly
+  different internal organizations, but the whole team is working on finding
+  what the right abstraction points are for a unified codebase.
+
+* As part of the frontend work, Barry Wark also implemented an experimental
+  event notification system that various ipython components can use.  In the
+  next release the implications and use patterns of this system regarding the
+  various GUI options will be worked out.
+
+* IPython finally has a full test system, that can test docstrings with
+  IPython-specific functionality.  There are still a few pieces missing for it
+  to be widely accessible to all users (so they can run the test suite at any
+  time and report problems), but it now works for the developers.  We are
+  working hard on continuing to improve it, as this was probably IPython's
+  major Achilles heel (the lack of proper test coverage made it effectively
+  impossible to do large-scale refactoring).  The full test suite can now
+  be run using the :command:`iptest` command line program.
+
+* The notion of a task has been completely reworked.  An `ITask` interface has
+  been created.  This interface defines the methods that tasks need to
+  implement.  These methods are now responsible for things like submitting
+  tasks and processing results.  There are two basic task types:
+  :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but
+  renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on
+  a function.
+
+* A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to
+  standardize the idea of a `map` method.  This interface has a single `map`
+  method that has the same syntax as the built-in `map`.  We have also defined
+  a `mapper` factory interface that creates objects that implement
+  :class:`IPython.kernel.mapper.IMapper` for different controllers.  Both the
+  multiengine and task controller now have mapping capabilties.
+
+* The parallel function capabilities have been reworks.  The major changes are
+  that i) there is now an `@parallel` magic that creates parallel functions,
+  ii) the syntax for mulitple variable follows that of `map`, iii) both the
+  multiengine and task controller now have a parallel function implementation.
 
+* All of the parallel computing capabilities from `ipython1-dev` have been
+  merged into IPython proper.  This resulted in the following new subpackages:
+  :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
+  :mod:`IPython.tools` and :mod:`IPython.testing`.
+
+* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and
+  friends have been completely refactored.  Now we are checking for
+  dependencies using the approach that matplotlib uses.
+
+* The documentation has been completely reorganized to accept the 
+  documentation from `ipython1-dev`.
+
+* We have switched to using Foolscap for all of our network protocols in
+  :mod:`IPython.kernel`.  This gives us secure connections that are both
+  encrypted and authenticated.
+
+* We have a brand new `COPYING.txt` files that describes the IPython license
+  and copyright. The biggest change is that we are putting "The IPython
+  Development Team" as the copyright holder. We give more details about
+  exactly what this means in this file. All developer should read this and use
+  the new banner in all IPython source code files.
+
+* sh profile: ./foo runs foo as system command, no need to do !./foo anymore
+
+* String lists now support ``sort(field, nums = True)`` method (to easily sort
+  system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``.
+
+* '%cpaste foo' now assigns the pasted block as string list, instead of string
+
+* The ipcluster script now run by default with no security.  This is done
+  because the main usage of the script is for starting things on localhost.
+  Eventually when ipcluster is able to start things on other hosts, we will put
+  security back.
+
+* 'cd --foo' searches directory history for string foo, and jumps to that dir.
+  Last part of dir name is checked first. If no matches for that are found,
+  look at the whole path.
+
+  
 Bug fixes
 ---------
 
-	* The colors escapes in the multiengine client are now turned off on win32 as they
-	  don't print correctly.
-	* The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing mpi_import_statement
-	  incorrectly, which was leading the engine to crash when mpi was enabled.
-	* A few subpackages has missing `__init__.py` files.
-	* The documentation is only created is Sphinx is found.  Previously, the `setup.py`
-	  script would fail if it was missing.
-	* Greedy 'cd' completion has been disabled again (it was enabled in 0.8.4)
+* The Windows installer has been fixed.  Now all IPython scripts have ``.bat``
+  versions created.  Also, the Start Menu shortcuts have been updated.
+
+* The colors escapes in the multiengine client are now turned off on win32 as
+  they don't print correctly.
+
+* The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing
+  mpi_import_statement incorrectly, which was leading the engine to crash when
+  mpi was enabled.
+
+* A few subpackages had missing ``__init__.py`` files.
+
+* The documentation is only created if Sphinx is found.  Previously, the
+  ``setup.py`` script would fail if it was missing.
+
+* Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as
+  it caused problems on certain platforms.
           
 
 Backwards incompatible changes
 ------------------------------
 
-	* :class:`IPython.kernel.client.Task` has been renamed
-	  :class:`IPython.kernel.client.StringTask` to make way for new task types.
-	* The keyword argument `style` has been renamed `dist` in `scatter`, `gather`
-	  and `map`.
-	* Renamed the values that the rename `dist` keyword argument can have from
-	  `'basic'` to `'b'`.
-	* IPython has a larger set of dependencies if you want all of its capabilities.
-	  See the `setup.py` script for details.
-	* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
-	  :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
-	  Instead they take the filename of a file that contains the FURL for that
-	  client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
-	  and the constructor can be left empty.
-	* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
-	  using the factory functions :func:`get_multiengine_client` and 
-	  :func:`get_task_client`.  These return a `Deferred` to the actual client.
-	* The command line options to `ipcontroller` and `ipengine` have changed to
-	  reflect the new Foolscap network protocol and the FURL files.  Please see the
-	  help for these scripts for details.
-	* The configuration files for the kernel have changed because of the Foolscap stuff.
-	  If you were using custom config files before, you should delete them and regenerate
-	  new ones.
+* The ``clusterfile`` options of the :command:`ipcluster` command has been
+  removed as it was not working and it will be replaced soon by something much
+  more robust.
+
+* The :mod:`IPython.kernel` configuration now properly find the user's
+  IPython directory.
+
+* In ipapi, the :func:`make_user_ns` function has been replaced with
+  :func:`make_user_namespaces`, to support dict subclasses in namespace
+  creation.
+
+* :class:`IPython.kernel.client.Task` has been renamed
+  :class:`IPython.kernel.client.StringTask` to make way for new task types.
+
+* The keyword argument `style` has been renamed `dist` in `scatter`, `gather`
+  and `map`.
+
+* Renamed the values that the rename `dist` keyword argument can have from
+  `'basic'` to `'b'`.
+
+* IPython has a larger set of dependencies if you want all of its capabilities.
+  See the `setup.py` script for details.
+
+* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
+  :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
+  Instead they take the filename of a file that contains the FURL for that
+  client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
+  and the constructor can be left empty.
+
+* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
+  using the factory functions :func:`get_multiengine_client` and 
+  :func:`get_task_client`.  These return a `Deferred` to the actual client.
+
+* The command line options to `ipcontroller` and `ipengine` have changed to
+  reflect the new Foolscap network protocol and the FURL files.  Please see the
+  help for these scripts for details.
+
+* The configuration files for the kernel have changed because of the Foolscap
+  stuff.  If you were using custom config files before, you should delete them
+  and regenerate new ones.
 
 Changes merged in from IPython1
 -------------------------------
 
 New features
 ............
 
-	* Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted
-	  and zope.interface are now easy installable, we can declare them as dependencies
-	  in our setupegg.py script.
-	* IPython is now compatible with Twisted 2.5.0 and 8.x.
-	* Added a new example of how to use :mod:`ipython1.kernel.asynclient`.
-	* Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
-	  been merged into IPython and is still in `ipython1-dev`.
-	* The ``TaskController`` now has methods for getting the queue status.
-	* The ``TaskResult`` objects not have information about how long the task
-	  took to run.
-	* We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
-	  we use to carry additional info around.
-	* New top-level module :mod:`asyncclient` that has asynchronous versions (that
-	  return deferreds) of the client classes.  This is designed to users who want
-	  to run their own Twisted reactor
-	* All the clients in :mod:`client` are now based on Twisted.  This is done by 
-	  running the Twisted reactor in a separate thread and using the
-	  :func:`blockingCallFromThread` function that is in recent versions of Twisted.
-	* Functions can now be pushed/pulled to/from engines using
-	  :meth:`MultiEngineClient.push_function` and :meth:`MultiEngineClient.pull_function`.
-	* Gather/scatter are now implemented in the client to reduce the work load
-	  of the controller and improve performance.
-	* Complete rewrite of the IPython docuementation.  All of the documentation
-	  from the IPython website has been moved into docs/source as restructured
-	  text documents.  PDF and HTML documentation are being generated using 
-	  Sphinx.
-	* New developer oriented documentation: development guidelines and roadmap. 
-	* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt`` file
-	  that is organized by release and is meant to provide something more relevant
-	  for users.
+* Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted and
+  zope.interface are now easy installable, we can declare them as dependencies
+  in our setupegg.py script.
+
+* IPython is now compatible with Twisted 2.5.0 and 8.x.
+
+* Added a new example of how to use :mod:`ipython1.kernel.asynclient`.
+
+* Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
+  been merged into IPython and is still in `ipython1-dev`.
+  
+* The ``TaskController`` now has methods for getting the queue status.
+
+* The ``TaskResult`` objects not have information about how long the task
+  took to run.
+  
+* We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
+  we use to carry additional info around.
+  
+* New top-level module :mod:`asyncclient` that has asynchronous versions (that
+  return deferreds) of the client classes.  This is designed to users who want
+  to run their own Twisted reactor.
+  
+* All the clients in :mod:`client` are now based on Twisted.  This is done by 
+  running the Twisted reactor in a separate thread and using the
+  :func:`blockingCallFromThread` function that is in recent versions of Twisted.
+
+* Functions can now be pushed/pulled to/from engines using
+  :meth:`MultiEngineClient.push_function` and
+  :meth:`MultiEngineClient.pull_function`.
+
+* Gather/scatter are now implemented in the client to reduce the work load
+  of the controller and improve performance.
+
+* Complete rewrite of the IPython docuementation.  All of the documentation
+  from the IPython website has been moved into docs/source as restructured
+  text documents.  PDF and HTML documentation are being generated using 
+  Sphinx.
+
+* New developer oriented documentation: development guidelines and roadmap. 
+
+* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt``
+  file that is organized by release and is meant to provide something more
+  relevant for users.
 
 Bug fixes
 .........
 
-	* Created a proper ``MANIFEST.in`` file to create source distributions.
-	* Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
-	  actions were being collected with a :class:`DeferredList` with 
-	  ``fireononeerrback=1``.  This meant that methods were returning 
-	  before all engines had given their results.  This was causing extremely odd 
-	  bugs in certain cases. To fix this problem, we have 1) set 
-	  ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
-	  before returning and 2) introduced a :exc:`CompositeError` exception 
-	  that wraps all of the engine exceptions.  This is a huge change as it means 
-	  that users will have to catch :exc:`CompositeError` rather than the actual
-	  exception.
+* Created a proper ``MANIFEST.in`` file to create source distributions.
+
+* Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
+  actions were being collected with a :class:`DeferredList` with 
+  ``fireononeerrback=1``.  This meant that methods were returning 
+  before all engines had given their results.  This was causing extremely odd 
+  bugs in certain cases. To fix this problem, we have 1) set 
+  ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
+  before returning and 2) introduced a :exc:`CompositeError` exception 
+  that wraps all of the engine exceptions.  This is a huge change as it means 
+  that users will have to catch :exc:`CompositeError` rather than the actual
+  exception.
 
 Backwards incompatible changes
 ..............................
 
-	* All names have been renamed to conform to the lowercase_with_underscore
-	  convention.  This will require users to change references to all names like
-	  ``queueStatus`` to ``queue_status``.
-	* Previously, methods like :meth:`MultiEngineClient.push` and    	
-	  :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was 
-	  becoming a problem as we weren't able to introduce new keyword arguments into
-	  the API.  Now these methods simple take a dict or sequence.  This has also allowed
-	  us to get rid of the ``*All`` methods like :meth:`pushAll` and :meth:`pullAll`.
-	  These things are now handled with the ``targets`` keyword argument that defaults
-	  to ``'all'``.
-	* The :attr:`MultiEngineClient.magicTargets` has been renamed to
-	  :attr:`MultiEngineClient.targets`. 
-	* All methods in the MultiEngine interface now accept the optional keyword argument
-	  ``block``.
-	* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
-	  :class:`TaskController` to :class:`TaskClient`.
-	* Renamed the top-level module from :mod:`api` to :mod:`client`.
-	* Most methods in the multiengine interface now raise a :exc:`CompositeError` exception
-	  that wraps the user's exceptions, rather than just raising the raw user's exception.
-	* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
-	  and ``pull``.
+* All names have been renamed to conform to the lowercase_with_underscore
+  convention.  This will require users to change references to all names like
+  ``queueStatus`` to ``queue_status``.
+
+* Previously, methods like :meth:`MultiEngineClient.push` and
+  :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was
+  becoming a problem as we weren't able to introduce new keyword arguments into
+  the API.  Now these methods simple take a dict or sequence.  This has also
+  allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and
+  :meth:`pullAll`.  These things are now handled with the ``targets`` keyword
+  argument that defaults to ``'all'``.
+
+* The :attr:`MultiEngineClient.magicTargets` has been renamed to
+  :attr:`MultiEngineClient.targets`. 
+
+* All methods in the MultiEngine interface now accept the optional keyword
+  argument ``block``.
+
+* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
+  :class:`TaskController` to :class:`TaskClient`.
+
+* Renamed the top-level module from :mod:`api` to :mod:`client`.
 
+* Most methods in the multiengine interface now raise a :exc:`CompositeError`
+  exception that wraps the user's exceptions, rather than just raising the raw
+  user's exception.
+
+* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
+  and ``pull``.
+
+  
 Release 0.8.4
 =============
 
-Someone needs to describe what went into 0.8.4.
+This was a quick release to fix an unfortunate bug that slipped into the 0.8.3
+release.  The ``--twisted`` option was disabled, as it turned out to be broken
+across several platforms.
 
-Release 0.8.2
-=============
 
-* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
-  and jumps to /foo. The current behaviour is closer to the documented 
-  behaviour, and should not trip anyone.
-  
 Release 0.8.3
 =============
   
 * pydb is now disabled by default (due to %run -d problems). You can enable
   it by passing -pydb command line argument to IPython. Note that setting
   it in config file won't work.
 
+  
+Release 0.8.2
+=============
+
+* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
+  and jumps to /foo. The current behaviour is closer to the documented 
+  behaviour, and should not trip anyone.
+
+  
 Older releases
 ==============
 
-Changes in earlier releases of IPython are described in the older file ``ChangeLog``.  
-Please refer to this document for details.
+Changes in earlier releases of IPython are described in the older file
+``ChangeLog``.  Please refer to this document for details.
 

docs/source/conf.py

@@ -1,166 +1,187
 # -*- coding: utf-8 -*-
 #
-# IPython documentation build configuration file, created by
-# sphinx-quickstart on Thu May  8 16:45:02 2008.
+# IPython documentation build configuration file.
+
+# NOTE: This file has been edited manually from the auto-generated one from
+# sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
+# needed, generate a scratch one and merge by hand any new fields needed.
+
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
 import sys, os
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
-#sys.path.append(os.path.abspath('some/directory'))
+sys.path.append(os.path.abspath('../sphinxext'))
+
+# Import support for ipython console session syntax highlighting (lives
+# in the sphinxext directory defined above)
+import ipython_console_highlighting
+
+# We load the ipython release info into a dict by explicit execution
+iprelease = {}
+execfile('../../IPython/Release.py',iprelease)
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-#extensions = []
+extensions = ['sphinx.ext.autodoc',
+              'inheritance_diagram', 'only_directives',
+              'ipython_console_highlighting', 
+              # 'plot_directive', # disabled for now, needs matplotlib
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.txt'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = '2008, The IPython Development Team'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
-# The short X.Y version.
-version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.beta1'
+release = iprelease['version']
+# The short X.Y version.
+version = '.'.join(release.split('.',2)[:2])
+
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
-#exclude_dirs = []
+exclude_dirs = ['attic']
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 
 # Options for HTML output
 # -----------------------
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
 html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 
 # If false, no module index is generated.
 #html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'IPythondoc'
+htmlhelp_basename = 'ipythondoc'
 
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
 latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 
-latex_documents = [ ('index', 'IPython.tex', 'IPython Documentation',
-                     ur"""Brian Granger, Fernando Pérez and Ville Vainio\\
-                     \ \\
-                     With contributions from:\\
-                     Benjamin Ragan-Kelley.""",
+latex_documents = [ ('index', 'ipython.tex', 'IPython Documentation',
+                     ur"""The IPython Development Team""",
                      'manual'),
                     ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 #latex_use_modindex = True
+
+
+# Cleanup
+# -------
+# delete release info to avoid pickling errors from sphinx
+
+del iprelease

docs/source/config/customization.txt

@@ -1,284 +1,286
 .. _customization:
 
 ========================
 Customization of IPython
 ========================
 
 There are 2 ways to configure IPython - the old way of using ipythonrc
 files (an INI-file like format), and the new way that involves editing
 your ipy_user_conf.py. Both configuration systems work at the same
 time, so you can set your options in both, but if you are hesitating
 about which alternative to choose, we recommend the ipy_user_conf.py
 approach, as it will give you more power and control in the long
 run. However, there are few options such as pylab_import_all that can
 only be specified in ipythonrc file or command line - the reason for
 this is that they are needed before IPython has been started up, and
 the IPApi object used in ipy_user_conf.py is not yet available at that
 time. A hybrid approach of specifying a few options in ipythonrc and
 doing the more advanced configuration in ipy_user_conf.py is also
 possible.
 
+.. _ipythonrc:
+
 The ipythonrc approach
 ======================
 
 As we've already mentioned, IPython reads a configuration file which can
 be specified at the command line (-rcfile) or which by default is
 assumed to be called ipythonrc. Such a file is looked for in the current
 directory where IPython is started and then in your IPYTHONDIR, which
 allows you to have local configuration files for specific projects. In
 this section we will call these types of configuration files simply
 rcfiles (short for resource configuration file).
 
 The syntax of an rcfile is one of key-value pairs separated by
 whitespace, one per line. Lines beginning with a # are ignored as
 comments, but comments can not be put on lines with data (the parser is
 fairly primitive). Note that these are not python files, and this is
 deliberate, because it allows us to do some things which would be quite
 tricky to implement if they were normal python files.
 
-First, an rcfile can contain permanent default values for almost all
-command line options (except things like -help or -Version). Sec
-`command line options`_ contains a description of all command-line
-options. However, values you explicitly specify at the command line
-override the values defined in the rcfile.
+First, an rcfile can contain permanent default values for almost all command
+line options (except things like -help or -Version). :ref:`This section
+<command_line_options>` contains a description of all command-line
+options. However, values you explicitly specify at the command line override
+the values defined in the rcfile.
 
 Besides command line option values, the rcfile can specify values for
 certain extra special options which are not available at the command
 line. These options are briefly described below.
 
 Each of these options may appear as many times as you need it in the file.
 
     * include <file1> <file2> ...: you can name other rcfiles you want
       to recursively load up to 15 levels (don't use the <> brackets in
       your names!). This feature allows you to define a 'base' rcfile
       with general options and special-purpose files which can be loaded
       only when needed with particular configuration options. To make
       this more convenient, IPython accepts the -profile <name> option
       (abbreviates to -p <name>) which tells it to look for an rcfile
       named ipythonrc-<name>.
     * import_mod <mod1> <mod2> ...: import modules with 'import
       <mod1>,<mod2>,...'
     * import_some <mod> <f1> <f2> ...: import functions with 'from
       <mod> import <f1>,<f2>,...'
     * import_all <mod1> <mod2> ...: for each module listed import
       functions with ``from <mod> import *``.
     * execute <python code>: give any single-line python code to be
       executed.
     * execfile <filename>: execute the python file given with an
       'execfile(filename)' command. Username expansion is performed on
       the given names. So if you need any amount of extra fancy
       customization that won't fit in any of the above 'canned' options,
       you can just put it in a separate python file and execute it.
     * alias <alias_def>: this is equivalent to calling
       '%alias <alias_def>' at the IPython command line. This way, from
       within IPython you can do common system tasks without having to
       exit it or use the ! escape. IPython isn't meant to be a shell
       replacement, but it is often very useful to be able to do things
       with files while testing code. This gives you the flexibility to
       have within IPython any aliases you may be used to under your
       normal system shell.
 
 ipy_user_conf.py
 ================
 
 There should be a simple template ipy_user_conf.py file in your
 ~/.ipython directory. It is a plain python module that is imported
 during IPython startup, so you can do pretty much what you want there
 - import modules, configure extensions, change options, define magic
 commands, put variables and functions in the IPython namespace,
 etc. You use the IPython extension api object, acquired by
 IPython.ipapi.get() and documented in the "IPython extension API"
 chapter, to interact with IPython. A sample ipy_user_conf.py is listed
 below for reference::
 
     # Most of your config files and extensions will probably start
     # with this import
 
     import IPython.ipapi
     ip = IPython.ipapi.get()
 
     # You probably want to uncomment this if you did %upgrade -nolegacy
     # import ipy_defaults    
 
     import os   
 
     def main():   
 
         #ip.dbg.debugmode = True
         ip.dbg.debug_stack()
 
         # uncomment if you want to get ipython -p sh behaviour
         # without having to use command line switches  
         import ipy_profile_sh
         import jobctrl
 
         # Configure your favourite editor?
         # Good idea e.g. for %edit os.path.isfile
 
         #import ipy_editors
 
         # Choose one of these:
 
         #ipy_editors.scite()
         #ipy_editors.scite('c:/opt/scite/scite.exe')
         #ipy_editors.komodo()
         #ipy_editors.idle()
         # ... or many others, try 'ipy_editors??' after import to see them
 
         # Or roll your own:
         #ipy_editors.install_editor("c:/opt/jed +$line $file")
 
 
         o = ip.options
         # An example on how to set options
         #o.autocall = 1
         o.system_verbose = 0
 
         #import_all("os sys")
         #execf('~/_ipython/ns.py')
 
 
         # -- prompt
         # A different, more compact set of prompts from the default ones, that
         # always show your current location in the filesystem:
 
         #o.prompt_in1 = r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Normal\n\C_Green|\#>'
         #o.prompt_in2 = r'.\D: '
         #o.prompt_out = r'[\#] '
 
         # Try one of these color settings if you can't read the text easily
         # autoexec is a list of IPython commands to execute on startup
         #o.autoexec.append('%colors LightBG')
         #o.autoexec.append('%colors NoColor')
         o.autoexec.append('%colors Linux')
 
 
     # some config helper functions you can use 
     def import_all(modules):
         """ Usage: import_all("os sys") """ 
         for m in modules.split():
             ip.ex("from %s import *" % m)
 
     def execf(fname):
         """ Execute a file in user namespace """
         ip.ex('execfile("%s")' % os.path.expanduser(fname))
 
     main()
 
 .. _Prompts:
 
 Fine-tuning your prompt
 =======================
 
 IPython's prompts can be customized using a syntax similar to that of
 the bash shell. Many of bash's escapes are supported, as well as a few
 additional ones. We list them below::
 
     \#
         the prompt/history count number. This escape is automatically
         wrapped in the coloring codes for the currently active color scheme. 
     \N
         the 'naked' prompt/history count number: this is just the number
         itself, without any coloring applied to it. This lets you produce
         numbered prompts with your own colors. 
     \D
         the prompt/history count, with the actual digits replaced by dots.
         Used mainly in continuation prompts (prompt_in2) 
     \w
         the current working directory 
     \W
         the basename of current working directory 
     \Xn
         where $n=0\ldots5.$ The current working directory, with $HOME
         replaced by ~, and filtered out to contain only $n$ path elements 
     \Yn
         Similar to \Xn, but with the $n+1$ element included if it is ~ (this
         is similar to the behavior of the %cn escapes in tcsh) 
     \u
         the username of the current user 
     \$
         if the effective UID is 0, a #, otherwise a $ 
     \h
         the hostname up to the first '.' 
     \H
         the hostname 
     \n
         a newline 
     \r
         a carriage return 
     \v
         IPython version string 
 
 In addition to these, ANSI color escapes can be insterted into the
 prompts, as \C_ColorName. The list of valid color names is: Black, Blue,
 Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray,
 LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White,
 Yellow.
 
 Finally, IPython supports the evaluation of arbitrary expressions in
 your prompt string. The prompt strings are evaluated through the syntax
 of PEP 215, but basically you can use $x.y to expand the value of x.y,
 and for more complicated expressions you can use braces: ${foo()+x} will
 call function foo and add to it the value of x, before putting the
 result into your prompt. For example, using
 prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' 
 will print the result of the uptime command on each prompt (assuming the
 commands module has been imported in your ipythonrc file).
 
 
       Prompt examples
 
 The following options in an ipythonrc file will give you IPython's
 default prompts::
 
     prompt_in1 'In [\#]:' 
     prompt_in2 '   .\D.:' 
     prompt_out 'Out[\#]:'
 
 which look like this::
 
     In [1]: 1+2 
     Out[1]: 3
 
     In [2]: for i in (1,2,3): 
        ...:    print i, 
        ...: 
     1 2 3
 
 These will give you a very colorful prompt with path information::
 
     #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' 
     prompt_in2 ' ..\D>' 
     prompt_out '<\#>'
 
 which look like this::
 
     fperez[~/ipython]1> 1+2 
                     <1> 3 
     fperez[~/ipython]2> for i in (1,2,3): 
                    ...>     print i, 
                    ...> 
     1 2 3
 
 
 .. _Profiles:
 
 IPython profiles
 ================
 
-As we already mentioned, IPython supports the -profile command-line
-option (see sec. `command line options`_). A profile is nothing more
-than a particular configuration file like your basic ipythonrc one,
-but with particular customizations for a specific purpose. When you
-start IPython with 'ipython -profile <name>', it assumes that in your
-IPYTHONDIR there is a file called ipythonrc-<name> or
-ipy_profile_<name>.py, and loads it instead of the normal ipythonrc.
+As we already mentioned, IPython supports the -profile command-line option (see
+:ref:`here <command_line_options>`).  A profile is nothing more than a
+particular configuration file like your basic ipythonrc one, but with
+particular customizations for a specific purpose. When you start IPython with
+'ipython -profile <name>', it assumes that in your IPYTHONDIR there is a file
+called ipythonrc-<name> or ipy_profile_<name>.py, and loads it instead of the
+normal ipythonrc.
 
 This system allows you to maintain multiple configurations which load
 modules, set options, define functions, etc. suitable for different
 tasks and activate them in a very simple manner. In order to avoid
 having to repeat all of your basic options (common things that don't
 change such as your color preferences, for example), any profile can
 include another configuration file. The most common way to use profiles
 is then to have each one include your basic ipythonrc file as a starting
 point, and then add further customizations.
  No newline at end of file

docs/source/config/index.txt

@@ -1,10 +1,10
 ===============================
 Configuration and customization
 ===============================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    initial_config.txt
    customization.txt
    new_config.txt

docs/source/config/initial_config.txt

@@ -1,243 +1,244
 .. _initial config:
 
 =========================================
 Initial configuration of your environment
 =========================================
 
 This section will help you set various things in your environment for
 your IPython sessions to be as efficient as possible. All of IPython's
 configuration information, along with several example files, is stored
 in a directory named by default $HOME/.ipython. You can change this by
 defining the environment variable IPYTHONDIR, or at runtime with the
 command line option -ipythondir.
 
-If all goes well, the first time you run IPython it should
-automatically create a user copy of the config directory for you,
-based on its builtin defaults. You can look at the files it creates to
-learn more about configuring the system. The main file you will modify
-to configure IPython's behavior is called ipythonrc (with a .ini
-extension under Windows), included for reference in `ipythonrc`_
-section. This file is very commented and has many variables you can
-change to suit your taste, you can find more details in
-Sec. customization_. Here we discuss the basic things you will want to
-make sure things are working properly from the beginning.
+If all goes well, the first time you run IPython it should automatically create
+a user copy of the config directory for you, based on its builtin defaults. You
+can look at the files it creates to learn more about configuring the
+system. The main file you will modify to configure IPython's behavior is called
+ipythonrc (with a .ini extension under Windows), included for reference
+:ref:`here <ipythonrc>`. This file is very commented and has many variables you
+can change to suit your taste, you can find more details :ref:`here
+<customization>`. Here we discuss the basic things you will want to make sure
+things are working properly from the beginning.
 
 
-.. _Accessing help:
+.. _accessing_help:
 
 Access to the Python help system
 ================================
 
-This is true for Python in general (not just for IPython): you should
-have an environment variable called PYTHONDOCS pointing to the directory
-where your HTML Python documentation lives. In my system it's
-/usr/share/doc/python-docs-2.3.4/html, check your local details or ask
-your systems administrator.
+This is true for Python in general (not just for IPython): you should have an
+environment variable called PYTHONDOCS pointing to the directory where your
+HTML Python documentation lives. In my system it's
+:file:`/usr/share/doc/python-doc/html`, check your local details or ask your
+systems administrator.
 
 This is the directory which holds the HTML version of the Python
 manuals. Unfortunately it seems that different Linux distributions
 package these files differently, so you may have to look around a bit.
 Below I show the contents of this directory on my system for reference::
 
     [html]> ls
-    about.dat acks.html dist/ ext/ index.html lib/ modindex.html
-    stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
+    about.html  dist/  icons/      lib/           python2.5.devhelp.gz  whatsnew/
+    acks.html   doc/   index.html  mac/           ref/
+    api/        ext/   inst/       modindex.html  tut/
 
 You should really make sure this variable is correctly set so that
 Python's pydoc-based help system works. It is a powerful and convenient
 system with full access to the Python manuals and all modules accessible
 to you.
 
 Under Windows it seems that pydoc finds the documentation automatically,
 so no extra setup appears necessary.
 
 
 Editor
 ======
 
 The %edit command (and its alias %ed) will invoke the editor set in your
 environment as EDITOR. If this variable is not set, it will default to
 vi under Linux/Unix and to notepad under Windows. You may want to set
 this variable properly and to a lightweight editor which doesn't take
 too long to start (that is, something other than a new instance of
 Emacs). This way you can edit multi-line code quickly and with the power
 of a real editor right inside IPython.
 
 If you are a dedicated Emacs user, you should set up the Emacs server so
 that new requests are handled by the original process. This means that
 almost no time is spent in handling the request (assuming an Emacs
 process is already running). For this to work, you need to set your
 EDITOR environment variable to 'emacsclient'. The code below, supplied
 by Francois Pinard, can then be used in your .emacs file to enable the
 server::
 
     (defvar server-buffer-clients)
     (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
       (server-start)
       (defun fp-kill-server-with-buffer-routine ()
         (and server-buffer-clients (server-done)))
       (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
 
 You can also set the value of this editor via the commmand-line option
 '-editor' or in your ipythonrc file. This is useful if you wish to use
 specifically for IPython an editor different from your typical default
 (and for Windows users who tend to use fewer environment variables).
 
 
 Color
 =====
 
 The default IPython configuration has most bells and whistles turned on
 (they're pretty safe). But there's one that may cause problems on some
 systems: the use of color on screen for displaying information. This is
 very useful, since IPython can show prompts and exception tracebacks
 with various colors, display syntax-highlighted source code, and in
 general make it easier to visually parse information.
 
 The following terminals seem to handle the color sequences fine:
 
     * Linux main text console, KDE Konsole, Gnome Terminal, E-term,
       rxvt, xterm.
     * CDE terminal (tested under Solaris). This one boldfaces light colors.
     * (X)Emacs buffers. See the emacs_ section for more details on
       using IPython with (X)Emacs.
     * A Windows (XP/2k) command prompt with pyreadline_.
     * A Windows (XP/2k) CygWin shell. Although some users have reported
       problems; it is not clear whether there is an issue for everyone
       or only under specific configurations. If you have full color
       support under cygwin, please post to the IPython mailing list so
       this issue can be resolved for all users.
 
+.. _pyreadline: https://code.launchpad.net/pyreadline
+      
 These have shown problems:
 
     * Windows command prompt in WinXP/2k logged into a Linux machine via
       telnet or ssh.
     * Windows native command prompt in WinXP/2k, without Gary Bishop's
       extensions. Once Gary's readline library is installed, the normal
       WinXP/2k command prompt works perfectly.
 
 Currently the following color schemes are available:
 
     * NoColor: uses no color escapes at all (all escapes are empty '' ''
       strings). This 'scheme' is thus fully safe to use in any terminal.
     * Linux: works well in Linux console type environments: dark
       background with light fonts. It uses bright colors for
       information, so it is difficult to read if you have a light
       colored background.
     * LightBG: the basic colors are similar to those in the Linux scheme
       but darker. It is easy to read in terminals with light backgrounds.
 
 IPython uses colors for two main groups of things: prompts and
 tracebacks which are directly printed to the terminal, and the object
 introspection system which passes large sets of data through a pager.
 
 
 Input/Output prompts and exception tracebacks
 =============================================
 
 You can test whether the colored prompts and tracebacks work on your
 system interactively by typing '%colors Linux' at the prompt (use
 '%colors LightBG' if your terminal has a light background). If the input
 prompt shows garbage like::
 
     [0;32mIn [[1;32m1[0;32m]: [0;00m
 
 instead of (in color) something like::
 
     In [1]:
 
 this means that your terminal doesn't properly handle color escape
 sequences. You can go to a 'no color' mode by typing '%colors NoColor'.
 
 You can try using a different terminal emulator program (Emacs users,
 see below). To permanently set your color preferences, edit the file
 $HOME/.ipython/ipythonrc and set the colors option to the desired value.
 
 
 Object details (types, docstrings, source code, etc.)
 =====================================================
 
-IPython has a set of special functions for studying the objects you
-are working with, discussed in detail in Sec. `dynamic object
-information`_. But this system relies on passing information which is
-longer than your screen through a data pager, such as the common Unix
-less and more programs. In order to be able to see this information in
-color, your pager needs to be properly configured. I strongly
-recommend using less instead of more, as it seems that more simply can
+IPython has a set of special functions for studying the objects you are working
+with, discussed in detail :ref:`here <dynamic_object_info>`. But this system
+relies on passing information which is longer than your screen through a data
+pager, such as the common Unix less and more programs. In order to be able to
+see this information in color, your pager needs to be properly configured. I
+strongly recommend using less instead of more, as it seems that more simply can
 not understand colored text correctly.
 
 In order to configure less as your default pager, do the following:
 
    1. Set the environment PAGER variable to less.
    2. Set the environment LESS variable to -r (plus any other options
       you always want to pass to less by default). This tells less to
       properly interpret control sequences, which is how color
       information is given to your terminal.
 
 For the csh or tcsh shells, add to your ~/.cshrc file the lines::
 
     setenv PAGER less
     setenv LESS -r
 
 There is similar syntax for other Unix shells, look at your system
 documentation for details.
 
 If you are on a system which lacks proper data pagers (such as Windows),
 IPython will use a very limited builtin pager.
 
 .. _emacs:
 
 (X)Emacs configuration
 ======================
 
 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
 currently (X)Emacs and IPython get along very well.
 
 Important note: You will need to use a recent enough version of
 python-mode.el, along with the file ipython.el. You can check that the
 version you have of python-mode.el is new enough by either looking at
 the revision number in the file itself, or asking for it in (X)Emacs via
 M-x py-version. Versions 4.68 and newer contain the necessary fixes for
 proper IPython support.
 
 The file ipython.el is included with the IPython distribution, in the
 documentation directory (where this manual resides in PDF and HTML
 formats).
 
 Once you put these files in your Emacs path, all you need in your .emacs
 file is::
 
     (require 'ipython)
 
 This should give you full support for executing code snippets via
 IPython, opening IPython as your Python shell via ``C-c !``, etc.
 
 You can customize the arguments passed to the IPython instance at startup by
 setting the ``py-python-command-args`` variable.  For example, to start always
 in ``pylab`` mode with hardcoded light-background colors, you can use::
 
     (setq py-python-command-args '("-pylab" "-colors" "LightBG"))
 
 If you happen to get garbage instead of colored prompts as described in
 the previous section, you may need to set also in your .emacs file::
 
     (setq ansi-color-for-comint-mode t)
 
 Notes:
 
     * There is one caveat you should be aware of: you must start the
       IPython shell before attempting to execute any code regions via
       ``C-c |``. Simply type C-c ! to start IPython before passing any code
       regions to the interpreter, and you shouldn't experience any
       problems.
       This is due to a bug in Python itself, which has been fixed for
       Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [
       737947 ]).
     * The (X)Emacs support is maintained by Alexander Schmolck, so all
       comments/requests should be directed to him through the IPython
       mailing lists.
     * This code is still somewhat experimental so it's a bit rough
       around the edges (although in practice, it works quite well).
     * Be aware that if you customize py-python-command previously, this
       value will override what ipython.el does (because loading the
       customization variables comes later).

docs/source/credits.txt

@@ -1,139 +1,207
 .. _credits:
 
 =======
 Credits
 =======
 
-IPython is mainly developed by Fernando Pérez
-<[e-mail]>, but the project was born from mixing in
-Fernando's code with the IPP project by Janko Hauser
-<jhauser-AT-zscout.de> and LazyPython by Nathan Gray
-<n8gray-AT-caltech.edu>. For all IPython-related requests, please
-contact Fernando.
-
-As of early 2006, the following developers have joined the core team:
-
-    * [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
-      Google Summer of Code project to develop python interactive
-      notebooks (XML documents) and graphical interface. This project
-      was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
-      Toni Alatalo <antont-AT-an.org>
-    * [Brian Granger] <bgranger-AT-scu.edu>: extending IPython to allow
-      support for interactive parallel computing.
-    * [Ville Vainio] <vivainio-AT-gmail.com>: Ville is the new
-      maintainer for the main trunk of IPython after version 0.7.1.
+IPython is led by Fernando Pérez.
+
+As of this writing, the following developers have joined the core team:
+
+* [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
+  Google Summer of Code project to develop python interactive
+  notebooks (XML documents) and graphical interface. This project
+  was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
+  Toni Alatalo <antont-AT-an.org>.
+
+* [Brian Granger] <ellisonbg-AT-gmail.com>: extending IPython to allow
+  support for interactive parallel computing.
+
+* [Benjamin (Min) Ragan-Kelley]: key work on IPython's parallel
+  computing infrastructure.
+
+* [Ville Vainio] <vivainio-AT-gmail.com>: Ville has made many improvements
+  to the core of IPython and was the maintainer of the main IPython
+  trunk from version 0.7.1 to 0.8.4.
+
+* [Gael Varoquaux] <gael.varoquaux-AT-normalesup.org>: work on the merged
+  architecture for the interpreter as of version 0.9, implementing a new WX GUI
+  based on this system.
+
+* [Barry Wark] <barrywark-AT-gmail.com>: implementing a new Cocoa GUI, as well
+  as work on the new interpreter architecture and Twisted support.
+
+* [Laurent Dufrechou] <laurent.dufrechou-AT-gmail.com>: development of the WX
+  GUI support.
+
+* [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu>: maintainer of the
+  PyReadline project, necessary for IPython under windows.
+
 
 The IPython project is also very grateful to:
 
 Bill Bumgarner <bbum-AT-friday.com>: for providing the DPyGetOpt module
 which gives very powerful and convenient handling of command-line
 options (light years ahead of what Python 2.1.1's getopt module does).
 
 Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for
 convenient and powerful string interpolation with a much nicer syntax
 than formatting through the '%' operator.
 
 Arnd Baecker <baecker-AT-physik.tu-dresden.de>: for his many very useful
 suggestions and comments, and lots of help with testing and
 documentation checking. Many of IPython's newer features are a result of
 discussions with him (bugs are still my fault, not his).
 
 Obviously Guido van Rossum and the whole Python development team, that
 goes without saying.
 
 IPython's website is generously hosted at http://ipython.scipy.orgby
 Enthought (http://www.enthought.com). I am very grateful to them and all
 of the SciPy team for their contribution.
 
 Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>,
 an O'Reilly Python editor. His Oct/11/2001 article about IPP and
 LazyPython, was what got this project started. You can read it at:
 http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html.
 
-And last but not least, all the kind IPython users who have emailed new
-code, bug reports, fixes, comments and ideas. A brief list follows,
-please let me know if I have ommitted your name by accident:
-
-    * [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
-      color problem. This bug alone caused many lost hours and
-      frustration, many thanks to him for the fix. I've always been a
-      fan of Ogg & friends, now I have one more reason to like these folks.
-      Jack is also contributing with Debian packaging and many other
-      things.
-    * [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug
-      reports, bug fixes, ideas, lots more. The ipython.el mode for
-      (X)Emacs is Alex's code, providing full support for IPython under
-      (X)Emacs.
-    * [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
-      information, Fink package management.
-    * [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
-      around the exception handling idiosyncracies of WxPython. Readline
-      and color support for Windows.
-    * [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
-      improved readline support, including fixes for Python 2.3.
-    * [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
-    * [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
-    * [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
-    * [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
-    * [Philip Hisley] <compsys-AT-starpower.net>
-    * [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
-      more.
-    * [Robin Siebler] <robinsiebler-AT-starband.net>
-    * [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
-    * [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
-    * [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
-    * [Syver Enstad] <syver-en-AT-online.no> Windows setup.
-    * [Richard] <rxe-AT-renre-europe.com> Global embedding.
-    * [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
-      compatibility.
-    * [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
-      installation.
-    * [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
-    * [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
-      documentation fixes.
-    * [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
-      ideas. Patches for Windows installer.
-    * [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
-    * [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
-    * [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
-      Win32/CygWin.
-    * [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
-      nice, lightweight string interpolation.
-    * [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
-    * [Gever Tulley] <gever-AT-helium.com> Code contributions.
-    * [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
-    * [Oliver Sander] <osander-AT-gmx.de> Bug reports.
-    * [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
-      logging module.
-    * [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
-      Fixes, enhancement suggestions for system shell use.
-    * [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
-      reports on Windows installation issues. Contributed a true Windows
-      binary installer.
-    * [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
-      to traceback printing.
-    * [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
-      prompt specials.
-    * [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
-      the multithreaded IPython.
-    * [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
-      author, helped with all the development of support for matplotlib
-      in IPyhton, including making necessary changes to matplotlib itself.
-    * [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
-    * [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
-      with (X)Emacs support, threading patches, ideas...
-    * [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
-      packaging and distribution.
-    * [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
-      tab-completing named arguments of user-defined functions.
-    * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
-      support implementation for searching namespaces.
-    * [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
-      so that when pdb is activated from within IPython, coloring, tab
-      completion and other features continue to work seamlessly.
-    * [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
-      editor invocation on syntax errors (see
-      http://www.scipy.net/roundup/ipython/issue36).
-    * [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
-      paging system.
-    * [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
  No newline at end of file
+And last but not least, all the kind IPython users who have emailed new code,
+bug reports, fixes, comments and ideas. A brief list follows, please let us
+know if we have ommitted your name by accident:
+
+* Dan Milstein <danmil-AT-comcast.net>.  A bold refactoring of the 
+  core prefilter stuff in the IPython interpreter.
+
+* [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
+  color problem. This bug alone caused many lost hours and
+  frustration, many thanks to him for the fix. I've always been a
+  fan of Ogg & friends, now I have one more reason to like these folks.
+  Jack is also contributing with Debian packaging and many other
+  things.
+ 
+* [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug
+  reports, bug fixes, ideas, lots more. The ipython.el mode for
+  (X)Emacs is Alex's code, providing full support for IPython under
+  (X)Emacs.
+
+* [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
+  information, Fink package management.
+
+* [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
+  around the exception handling idiosyncracies of WxPython. Readline
+  and color support for Windows.
+
+* [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
+  improved readline support, including fixes for Python 2.3.
+
+* [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
+
+* [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
+
+* [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
+
+* [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
+
+* [Philip Hisley] <compsys-AT-starpower.net>
+
+* [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
+  more.
+
+* [Robin Siebler] <robinsiebler-AT-starband.net>
+
+* [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
+
+* [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
+
+* [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
+
+* [Syver Enstad] <syver-en-AT-online.no> Windows setup.
+
+* [Richard] <rxe-AT-renre-europe.com> Global embedding.
+
+* [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
+  compatibility.
+  
+* [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
+  installation.
+  
+* [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
+
+* [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
+  documentation fixes.
+  
+* [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
+  ideas. Patches for Windows installer.
+  
+* [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
+
+* [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
+
+* [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
+  Win32/CygWin.
+  
+* [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
+  nice, lightweight string interpolation.
+  
+* [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
+
+* [Gever Tulley] <gever-AT-helium.com> Code contributions.
+
+* [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
+
+* [Oliver Sander] <osander-AT-gmx.de> Bug reports.
+
+* [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
+  logging module.
+
+* [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
+  Fixes, enhancement suggestions for system shell use.
+
+* [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
+  reports on Windows installation issues. Contributed a true Windows
+  binary installer.
+
+* [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
+  to traceback printing.
+
+* [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
+  prompt specials.
+
+* [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
+  the multithreaded IPython.
+
+* [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
+  author, helped with all the development of support for matplotlib
+  in IPyhton, including making necessary changes to matplotlib itself.
+
+* [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
+
+* [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
+  with (X)Emacs support, threading patches, ideas...
+
+* [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
+  packaging and distribution.
+
+* [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
+  tab-completing named arguments of user-defined functions.
+
+* [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
+  support implementation for searching namespaces.
+
+* [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
+  so that when pdb is activated from within IPython, coloring, tab
+  completion and other features continue to work seamlessly.
+
+* [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
+  editor invocation on syntax errors (see
+  http://www.scipy.net/roundup/ipython/issue36).
+
+* [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
+  paging system.
+
+* [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
+
+* [Ondrej Certik] <ondrej-AT-certik.cz>: set up the IPython docs to use the new
+  Sphinx system used by Python, Matplotlib and many more projects.
+
+* [Stefan van der Walt] <stefan-AT-sun.ac.za>: support for the new config system.

docs/source/development/development.txt

@@ -1,360 +1,310
 .. _development:
 
-==================================
+==============================
 IPython development guidelines
-==================================
-
-.. contents::
+==============================
 
 
 Overview
 ========
 
-IPython is the next generation of IPython.  It is named such for two reasons:
-
-- Eventually, IPython will become IPython version 1.0.
-- This new code base needs to be able to co-exist with the existing IPython until
-  it is a full replacement for it.  Thus we needed a different name.  We couldn't
-  use ``ipython`` (lowercase) as some files systems are case insensitive.
-
-There are two, no three, main goals of the IPython effort:
-
-1. Clean up the existing codebase and write lots of tests.
-2. Separate the core functionality of IPython from the terminal to enable IPython
-   to be used from within a variety of GUI applications.
-3. Implement a system for interactive parallel computing.
-
-While the third goal may seem a bit unrelated to the main focus of IPython, it turns
-out that the technologies required for this goal are nearly identical with those
-required for goal two. This is the main reason the interactive parallel computing
-capabilities are being put into IPython proper. Currently the third of these goals is
-furthest along.
-
-This document describes IPython from the perspective of developers.  
+This document describes IPython from the perspective of developers. Most
+importantly, it gives information for people who want to contribute to the
+development of IPython. So if you want to help out, read on!
+
+How to contribute to IPython
+============================
+
+IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
+This makes it easy for people to contribute to the development of IPython.
+Here is a sketch of how to get going.
+
+Install Bazaar and create a Launchpad account
+---------------------------------------------
 
+First make sure you have installed Bazaar (see their `website
+<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
+you, try the following::
 
-Project organization
-====================
-
-Subpackages
------------
+    $ bzr whoami
+    Joe Coder <[e-mail]>
 
-IPython is organized into semi self-contained subpackages.  Each of the subpackages will have its own:
-
-- **Dependencies**.  One of the most important things to keep in mind in
-  partitioning code amongst subpackages, is that they should be used to cleanly
-  encapsulate dependencies.  
-- **Tests**.  Each subpackage shoud have its own ``tests`` subdirectory that
-  contains all of the tests for that package.  For information about writing tests
-  for IPython, see the `Testing System`_ section of this document.
-- **Configuration**.  Each subpackage should have its own ``config`` subdirectory
-  that contains the configuration information for the components of the 
-  subpackage.  For information about how the IPython configuration system
-  works, see the `Configuration System`_ section of this document.
-- **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory that
-  contains all of the command line scripts associated with the subpackage.
+This should display your name and email. Next, you will want to create an
+account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
+ssh keys. For more information of setting up your ssh keys, see `this link
+<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
 
-Installation and dependencies
------------------------------
-   
-IPython will not use `setuptools`_ for installation. Instead, we will use standard
-``setup.py`` scripts that use `distutils`_. While there are a number a extremely nice
-features that `setuptools`_ has (like namespace packages), the current implementation
-of `setuptools`_ has performance problems, particularly on shared file systems. In
-particular, when Python packages are installed on NSF file systems, import times
-become much too long (up towards 10 seconds). 
+Get the main IPython branch from Launchpad
+------------------------------------------
 
-Because IPython is being used extensively in the context of high performance
-computing, where performance is critical but shared file systems are common, we feel
-these performance hits are not acceptable. Thus, until the performance problems
-associated with `setuptools`_ are addressed, we will stick with plain `distutils`_. We
-are hopeful that these problems will be addressed and that we will eventually begin
-using `setuptools`_. Because of this, we are trying to organize IPython in a way that
-will make the eventual transition to `setuptools`_ as painless as possible.
+Now, you can get a copy of the main IPython development branch (we call this
+the "trunk")::
 
-Because we will be using `distutils`_, there will be no method for automatically installing dependencies.  Instead, we are following the approach of `Matplotlib`_ which can be summarized as follows:
+    $ bzr branch lp:ipython
 
-- Distinguish between required and optional dependencies.  However, the required
-  dependencies for IPython should be only the Python standard library.
-- Upon installation check to see which optional dependencies are present and tell
-  the user which parts of IPython need which optional dependencies.
+Create a working branch
+-----------------------
 
-It is absolutely critical that each subpackage of IPython has a clearly specified set
-of dependencies and that dependencies are not carelessly inherited from other IPython
-subpackages. Furthermore, tests that have certain dependencies should not fail if
-those dependencies are not present. Instead they should be skipped and print a
-message.
+When working on IPython, you won't actually make edits directly to the
+:file:`lp:ipython` branch. Instead, you will create a separate branch for your
+changes. For now, let's assume you want to do your work in a branch named
+"ipython-mybranch". Create this branch by doing::
 
-.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
-.. _distutils: http://docs.python.org/lib/module-distutils.html
-.. _Matplotlib: http://matplotlib.sourceforge.net/
+    $ bzr branch ipython ipython-mybranch
 
-Specific subpackages
---------------------
+When you actually create a branch, you will want to give it a name that
+reflects the nature of the work that you will be doing in it, like
+"install-docs-update".
 
-``core``
-	This is the core functionality of IPython that is independent of the
-	terminal, network and GUIs.  Most of the code that is in the current
-	IPython trunk will be refactored, cleaned up and moved here.
+Make edits in your working branch
+---------------------------------
 
-``kernel``
-	The enables the IPython core to be expose to a the network.  This is
-	also where all of the parallel computing capabilities are to be found.
-	
-``config``
-	The configuration package used by IPython.
+Now you are ready to actually make edits in your :file:`ipython-mybranch`
+branch. Before doing this, it is helpful to install this branch so you can
+test your changes as you work. This is easiest if you have setuptools
+installed. Then, just do::
 
-``frontends``
-	The various frontends for IPython.  A frontend is the end-user application
-	that exposes the capabilities of IPython to the user.  The most basic frontend
-	will simply be a terminal based application that looks just like today 's 
-	IPython.  Other frontends will likely be more powerful and based on GUI toolkits.
-
-``notebook``
-	An application that allows users to work with IPython notebooks.
-
-``tools``
-	This is where general utilities go.
+    $ cd ipython-mybranch
+    $ python setupegg.py develop
 
+Now, make some changes. After a while, you will want to commit your changes.
+This let's Bazaar know that you like the changes you have made and gives you
+an opportunity to keep a nice record of what you have done. This looks like
+this::
 
-Version control
-===============
-
-In the past, IPython development has been done using `Subversion`__.  Recently, we made the transition to using `Bazaar`__ and `Launchpad`__.  This makes it much easier for people
-to contribute code to IPython.  Here is a sketch of how to use Bazaar for IPython
-development.  First, you should install Bazaar.  After you have done that, make
-sure that it is working by getting the latest main branch of IPython::
-
-	$ bzr branch lp:ipython
-
-Now you can create a new branch for you to do your work in::
+    $ ...do work in ipython-mybranch...
+    $ bzr commit -m "the commit message goes here"
 
-	$ bzr branch ipython ipython-mybranch
-
-The typical work cycle in this branch will be to make changes in `ipython-mybranch`
-and then commit those changes using the commit command::
-
-	$ ...do work in ipython-mybranch...
-	$ bzr ci -m "the commit message goes here"
-
-Please note that since we now don't use an old-style linear ChangeLog
-(that tends to cause problems with distributed version control
-systems), you should ensure that your log messages are reasonably
-detailed.  Use a docstring-like approach in the commit messages
-(including the second line being left *blank*)::
+Please note that since we now don't use an old-style linear ChangeLog (that
+tends to cause problems with distributed version control systems), you should
+ensure that your log messages are reasonably detailed.  Use a docstring-like
+approach in the commit messages (including the second line being left
+*blank*)::
 
   Single line summary of  changes being committed.
 
-  - more details when warranted ...
-  - including crediting outside contributors if they sent the
+  * more details when warranted ...
+  * including crediting outside contributors if they sent the
     code/bug/idea!
 
-If we couple this with a policy of making single commits for each
-reasonably atomic change, the bzr log should give an excellent view of
-the project, and the `--short` log option becomes a nice summary.
+As you work, you will repeat this edit/commit cycle many times. If you work on
+your branch for a long time, you will also want to get the latest changes from
+the :file:`lp:ipython` branch. This can be done with the following sequence of
+commands::
 
-While working with this branch, it is a good idea to merge in changes that have been
-made upstream in the parent branch.  This can be done by doing::
+    $ ls
+    ipython
+    ipython-mybranch
+    
+    $ cd ipython
+    $ bzr pull
+    $ cd ../ipython-mybranch
+    $ bzr merge ../ipython
+    $ bzr commit -m "Merging changes from trunk"
 
-	$ bzr pull
-	
-If this command shows that the branches have diverged, then you should do a merge
-instead::
+Along the way, you should also run the IPython test suite.  You can do this using the :command:`iptest` command::
 
-	$ bzr merge lp:ipython
+    $ cd
+    $ iptest
 
-If you want others to be able to see your branch, you can create an account with
-launchpad and push the branch to your own workspace::
+The :command:`iptest` command will also pick up and run any tests you have written.
 
-	$ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch
+Post your branch and request a code review
+------------------------------------------
 
-Finally, once the work in your branch is done, you can merge your changes back into
-the `ipython` branch by using merge::
+Once you are done with your edits, you should post your branch on Launchpad so
+that other IPython developers can review the changes and help you merge your
+changes into the main development branch. To post your branch on Launchpad,
+do::
 
-	$ cd ipython
-	$ merge ../ipython-mybranch
-	[resolve any conflicts]
-	$ bzr ci -m "Fixing that bug"
-	$ bzr push
+    $ cd ipython-mybranch
+    $ bzr push lp:~yourusername/ipython/ipython-mybranch
 
-But this will require you to have write permissions to the `ipython` branch.  It you don't
-you can tell one of the IPython devs about your branch and they can do the merge for you.
+Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
+should see your branch under the "Code" tab. If you click on your branch, you
+can provide a short description of the branch as well as mark its status. Most
+importantly, you should click the link that reads "Propose for merging into
+another branch". What does this do?
 
-More information about Bazaar workflows can be found `here`__.
+This let's the other IPython developers know that your branch is ready to be
+reviewed and merged into the main development branch. During this review
+process, other developers will give you feedback and help you get your code
+ready to be merged. What types of things will we be looking for:
 
-.. __: http://subversion.tigris.org/
-.. __: http://bazaar-vcs.org/
-.. __: http://www.launchpad.net/ipython
-.. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html
+* All code is documented.
+* All code has tests.
+* The entire IPython test suite passes.
+
+Once your changes have been reviewed and approved, someone will merge them
+into the main development branch.
 
 Documentation
 =============
 
 Standalone documentation
 ------------------------
 
-All standalone documentation should be written in plain text (``.txt``) files using
-`reStructuredText`_ for markup and formatting. All such documentation should be placed
-in the top level directory ``docs`` of the IPython source tree. Or, when appropriate,
-a suitably named subdirectory should be used. The documentation in this location will
-serve as the main source for IPython documentation and all existing documentation
-should be converted to this format.
+All standalone documentation should be written in plain text (``.txt``) files
+using reStructuredText [reStructuredText]_ for markup and formatting. All such
+documentation should be placed in directory :file:`docs/source` of the IPython
+source tree. The documentation in this location will serve as the main source
+for IPython documentation and all existing documentation should be converted
+to this format.
 
-In the future, the text files in the ``docs`` directory will be used to generate all
-forms of documentation for IPython. This include documentation on the IPython website
-as well as *pdf* documentation.
+To build the final documentation, we use Sphinx [Sphinx]_.  Once you have Sphinx installed, you can build the html docs yourself by doing::
 
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+    $ cd ipython-mybranch/docs
+    $ make html
 
 Docstring format
 ----------------
 
-Good docstrings are very important. All new code will use `Epydoc`_ for generating API
-docs, so we will follow the `Epydoc`_ conventions. More specifically, we will use
-`reStructuredText`_ for markup and formatting, since it is understood by a wide
-variety of tools. This means that if in the future we have any reason to change from
-`Epydoc`_ to something else, we'll have fewer transition pains.
-
-Details about using `reStructuredText`_ for docstrings can be found `here
+Good docstrings are very important. All new code should have docstrings that
+are formatted using reStructuredText for markup and formatting, since it is
+understood by a wide variety of tools. Details about using reStructuredText
+for docstrings can be found `here
 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
 
-.. _Epydoc: http://epydoc.sourceforge.net/
-
 Additional PEPs of interest regarding documentation of code:
 
-- `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
-- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
-- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+* `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
+* `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
+* `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
 
 
 Coding conventions
 ==================
 
 General
 -------
 
-In general, we'll try to follow the standard Python style conventions as described here:
+In general, we'll try to follow the standard Python style conventions as
+described here:
 
-- `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
+* `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
 
 
 Other comments:
 
-- In a large file, top level classes and functions should be 
+* In a large file, top level classes and functions should be 
   separated by 2-3 lines to make it easier to separate them visually.
-- Use 4 spaces for indentation.
-- Keep the ordering of methods the same in classes that have the same 
-  methods.  This is particularly true for classes that implement 
-  similar interfaces and for interfaces that are similar.
+* Use 4 spaces for indentation.
+* Keep the ordering of methods the same in classes that have the same 
+  methods.  This is particularly true for classes that implement an interface.
 
 Naming conventions
 ------------------
 
-In terms of naming conventions, we'll follow the guidelines from the `Style Guide for
-Python Code`_.
+In terms of naming conventions, we'll follow the guidelines from the `Style
+Guide for Python Code`_.
 
 For all new IPython code (and much existing code is being refactored), we'll use:
 
-- All ``lowercase`` module names.
+* All ``lowercase`` module names.
 
-- ``CamelCase`` for class names.
+* ``CamelCase`` for class names.
 
-- ``lowercase_with_underscores`` for methods, functions, variables and attributes.
+* ``lowercase_with_underscores`` for methods, functions, variables and
+  attributes.
 
-This may be confusing as most of the existing IPython codebase uses a different convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will move IPython over to the new
-convention, providing shadow names for backward compatibility in public interfaces. 
+There are, however, some important exceptions to these rules. In some cases,
+IPython code will interface with packages (Twisted, Wx, Qt) that use other
+conventions. At some level this makes it impossible to adhere to our own
+standards at all times. In particular, when subclassing classes that use other
+naming conventions, you must follow their naming conventions. To deal with
+cases like this, we propose the following policy:
 
-There are, however, some important exceptions to these rules.  In some cases, IPython
-code will interface with packages (Twisted, Wx, Qt) that use other conventions.  At some level this makes it impossible to adhere to our own standards at all times.  In particular, when subclassing classes that use other naming conventions, you must follow their naming conventions.  To deal with cases like this, we propose the following policy:
+* If you are subclassing a class that uses different conventions, use its
+  naming conventions throughout your subclass.  Thus, if you are creating a
+  Twisted Protocol class, used Twisted's
+  ``namingSchemeForMethodsAndAttributes.``
 
-- If you are subclassing a class that uses different conventions, use its
-  naming conventions throughout your subclass.  Thus, if you are creating a 
-  Twisted Protocol class, used Twisted's ``namingSchemeForMethodsAndAttributes.``
+* All IPython's official interfaces should use our conventions.  In some cases
+  this will mean that you need to provide shadow names (first implement
+  ``fooBar`` and then ``foo_bar = fooBar``).  We want to avoid this at all
+  costs, but it will probably be necessary at times.  But, please use this
+  sparingly!
 
-- All IPython's official interfaces should use our conventions.  In some cases 
-  this will mean that you need to provide shadow names (first implement ``fooBar``
-  and then ``foo_bar = fooBar``).  We want to avoid this at all costs, but it 
-  will probably be necessary at times.  But, please use this sparingly!
+Implementation-specific *private* methods will use
+``_single_underscore_prefix``. Names with a leading double underscore will
+*only* be used in special cases, as they makes subclassing difficult (such
+names are not easily seen by child classes).
 
-Implementation-specific *private* methods will use ``_single_underscore_prefix``.
-Names with a leading double underscore will *only* be used in special cases, as they
-makes subclassing difficult (such names are not easily seen by child classes).
-
-Occasionally some run-in lowercase names are used, but mostly for very short names or
-where we are implementing methods very similar to existing ones in a base class (like
-``runlines()`` where ``runsource()`` and ``runcode()`` had established precedent).
+Occasionally some run-in lowercase names are used, but mostly for very short
+names or where we are implementing methods very similar to existing ones in a
+base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
+established precedent).
 
 The old IPython codebase has a big mix of classes and modules prefixed with an
-explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned upon, as
-namespaces offer cleaner prefixing. The only case where this approach is justified is
-for classes which are expected to be imported into external namespaces and a very
-generic name (like Shell) is too likely to clash with something else. We'll need to
-revisit this issue as we clean up and refactor the code, but in general we should
-remove as many unnecessary ``IP``/``ip`` prefixes as possible. However, if a prefix
-seems absolutely necessary the more specific ``IPY`` or ``ipy`` are preferred.
+explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
+upon, as namespaces offer cleaner prefixing. The only case where this approach
+is justified is for classes which are expected to be imported into external
+namespaces and a very generic name (like Shell) is too likely to clash with
+something else. We'll need to revisit this issue as we clean up and refactor
+the code, but in general we should remove as many unnecessary ``IP``/``ip``
+prefixes as possible. However, if a prefix seems absolutely necessary the more
+specific ``IPY`` or ``ipy`` are preferred.
 
 .. _devel_testing:
 
 Testing system
 ==============
 
-It is extremely important that all code contributed to IPython has tests. Tests should
-be written as unittests, doctests or as entities that the `Nose`_ testing package will
-find. Regardless of how the tests are written, we will use `Nose`_ for discovering and
-running the tests. `Nose`_ will be required to run the IPython test suite, but will
-not be required to simply use IPython.
-
-.. _Nose: http://code.google.com/p/python-nose/
+It is extremely important that all code contributed to IPython has tests.
+Tests should be written as unittests, doctests or as entities that the Nose
+[Nose]_ testing package will find. Regardless of how the tests are written, we
+will use Nose for discovering and running the tests. Nose will be required to
+run the IPython test suite, but will not be required to simply use IPython.
 
-Tests of `Twisted`__ using code should be written by subclassing the ``TestCase`` class
-that comes with ``twisted.trial.unittest``. When this is done, `Nose`_ will be able to
-run the tests and the twisted reactor will be handled correctly.
+Tests of Twisted using code need to follow two additional guidelines:
 
-.. __: http://www.twistedmatrix.com
+1. Twisted using tests should be written by subclassing the :class:`TestCase`
+   class that comes with :mod:`twisted.trial.unittest`. 
 
-Each subpackage in IPython should have its own ``tests`` directory that contains all
-of the tests for that subpackage. This allows each subpackage to be self-contained. If
-a subpackage has any dependencies beyond the Python standard library, the tests for
-that subpackage should be skipped if the dependencies are not found. This is very
-important so users don't get tests failing simply because they don't have dependencies.
+2. All :class:`Deferred` instances that are created in the test must be
+   properly chained and the final one *must* be the return value of the test
+   method.
 
-We also need to look into use Noses ability to tag tests to allow a more modular
-approach of running tests.
-
-.. _devel_config:
+When these two things are done, Nose will be able to run the tests and the
+twisted reactor will be handled correctly.
 
-Configuration system
-====================
+Each subpackage in IPython should have its own :file:`tests` directory that
+contains all of the tests for that subpackage. This allows each subpackage to
+be self-contained. If a subpackage has any dependencies beyond the Python
+standard library, the tests for that subpackage should be skipped if the
+dependencies are not found. This is very important so users don't get tests
+failing simply because they don't have dependencies.
 
-IPython uses `.ini`_ files for configuration purposes. This represents a huge
-improvement over the configuration system used in IPython. IPython works with these
-files using the `ConfigObj`_ package, which IPython includes as
-``ipython1/external/configobj.py``.
+To run the IPython test suite, use the :command:`iptest` command that is installed with IPython::
 
-Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of IPython
-should contain a ``config`` subdirectory that contains all of the configuration
-information for the subpackage. To see how configuration information is defined (along
-with defaults) see at the examples in ``ipython1/kernel/config`` and
-``ipython1/core/config``. Likewise, to see how the configuration information is used,
-see examples in ``ipython1/kernel/scripts/ipengine.py``.
-
-Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We are
-calling this new layer, ``tconfig``, as it will use a `Traits`_-like validation model.
-We won't actually use `Traits`_, but will implement something similar in pure Python.
-But, even in this new system, we will still use `ConfigObj`_ and `.ini`_ files
-underneath the hood. Talk to Fernando if you are interested in working on this part of
-IPython. The current prototype of ``tconfig`` is located in the IPython sandbox.
-
-.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
-.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
-.. _Traits: http://code.enthought.com/traits/
+    $ iptest
 
+This command runs Nose with the proper options and extensions.
 
+.. _devel_config:
 
+Release checklist
+=================
 
+Most of the release process is automated by the :file:`release` script in the
+:file:`tools` directory.  This is just a handy reminder for the release manager.
 
+#. Run the release script, which makes the tar.gz, eggs and Win32 .exe
+   installer.  It posts them to the site and registers the release with PyPI.
 
+#. Updating the website with announcements and links to the updated
+   changes.txt in html form. Remember to put a short note both on the news
+   page of the site and on Launcphad.
 
+#. Drafting a short release announcement with i) highlights and ii) a link to
+   the html changes.txt.
 
+#. Make sure that the released version of the docs is live on the site.
 
+#. Celebrate!
 
+.. [Bazaar] Bazaar. http://bazaar-vcs.org/
+.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
+.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
+.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
+.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/

docs/source/development/index.txt

@@ -1,9 +1,11
 ==================
 Development
 ==================
 
 .. toctree::
    :maxdepth: 2
 
    development.txt
    roadmap.txt
+   notification_blueprint.txt
+   config_blueprint.txt

docs/source/development/notification_blueprint.txt

@@ -1,47 +1,83
-.. Notification:
+.. _notification:
 
 ==========================================
 IPython.kernel.core.notification blueprint
 ==========================================
 
 Overview
 ========
-The :mod:`IPython.kernel.core.notification` module will provide a simple implementation of a notification center and support for the observer pattern within the :mod:`IPython.kernel.core`. The main intended use case is to provide notification of Interpreter events to an observing frontend during the execution of a single block of code.
+
+The :mod:`IPython.kernel.core.notification` module will provide a simple
+implementation of a notification center and support for the observer pattern
+within the :mod:`IPython.kernel.core`. The main intended use case is to
+provide notification of Interpreter events to an observing frontend during the
+execution of a single block of code.
 
 Functional Requirements
 =======================
+
 The notification center must:
-	* Provide synchronous notification of events to all registered observers.
-	* Provide typed or labeled notification types
-	* Allow observers to register callbacks for individual or all notification types
-	* Allow observers to register callbacks for events from individual or all notifying objects
-	* Notification to the observer consists of the notification type, notifying object and user-supplied extra information [implementation: as keyword parameters to the registered callback]
-	* Perform as O(1) in the case of no registered observers.
-	* Permit out-of-process or cross-network extension.
-	
+
+* Provide synchronous notification of events to all registered observers.
+
+* Provide typed or labeled notification types.
+
+* Allow observers to register callbacks for individual or all notification
+  types.
+
+* Allow observers to register callbacks for events from individual or all
+  notifying objects.
+
+* Notification to the observer consists of the notification type, notifying
+  object and user-supplied extra information [implementation: as keyword
+  parameters to the registered callback].
+
+* Perform as O(1) in the case of no registered observers.
+
+* Permit out-of-process or cross-network extension.
+    
 What's not included
-==============================================================
+===================
+
 As written, the :mod:`IPython.kernel.core.notificaiton` module does not:
- 	* Provide out-of-process or network notifications [these should be handled by a separate, Twisted aware module in :mod:`IPython.kernel`].
-	* Provide zope.interface-style interfaces for the notification system [these should also be provided by the :mod:`IPython.kernel` module]
-	
+
+* Provide out-of-process or network notifications (these should be handled by
+  a separate, Twisted aware module in :mod:`IPython.kernel`).
+
+* Provide zope.interface-style interfaces for the notification system (these
+  should also be provided by the :mod:`IPython.kernel` module).
+    
 Use Cases
 =========
+
 The following use cases describe the main intended uses of the notificaiton module and illustrate the main success scenario for each use case:
 
-	1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code::
-		from IPython.kernel.core.notification import NotificationCenter
-		center = NotificationCenter.sharedNotificationCenter
-		center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification)
-	
-	and elsewhere in his front end::
-		def stdout_notification(self, type, notifying_object, out_string=None):
-			self.writeStdOut(out_string)
-	
-	If everything works, the Interpreter will (according to its published API) fire a notification via the :data:`IPython.kernel.core.notification.sharedCenter` of type :const:`STD_OUT_NOTIFICATION_TYPE` before writing anything to stdout [it's up to the Intereter implementation to figure out when to do this]. The notificaiton center will then call the registered callbacks for that event type (in this case, Dwight's frontend's stdout_notification method). Again, according to its API, the Interpreter provides an additional keyword argument when firing the notificaiton of out_string, a copy of the string it will write to stdout.
-
-	Like magic, Dwight's frontend is able to provide output, even during long-running calculations. Now if Jim could just convince Dwight to use Twisted...
-
-	2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is stuck in the stone age, his frontend will be written in a new Fortran-like dialect of python and will run only from the command line. Because he doesn't need any fancy notification system and is used to worrying about every cycle on his rat-wheel powered mini, Boss Hog is adamant that the new notification system not produce any performance penalty. As they say in Hazard county, there's no such thing as a free lunch. If he wanted zero overhead, he should have kept using IPython 0.8. Instead, those tricky Duke boys slide in a suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module that imparts only a constant (and small) performance penalty when the Interpreter (or any other object) fires an event for which there are no registered observers. Of course, the same notificaiton-enabled Interpreter can then be used in frontends that require notifications, thus saving the IPython project from a nasty civil war.
-	
-	3. Barry is wrting a frontend for the IPython project. Because Barry's front end is the *new hotness*, it uses an asynchronous event model to communicate with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the :mod:`IPython.kernel.core.notification` module, Barry's frontend can register for notifications from the interpreter that are delivered asynchronously. Even if Barry's frontend is running on a separate process or even host from the Interpreter, the notifications are delivered, as if by dark and twisted magic. Just like Dwight's frontend, Barry's frontend can now recieve notifications of e.g. writing to stdout/stderr, opening/closing an external file, an exception in the executing code, etc.
  No newline at end of file
+    1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code::
+
+        from IPython.kernel.core.notification import NotificationCenter
+        center = NotificationCenter.sharedNotificationCenter
+        center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification)
+    
+    and elsewhere in his front end::
+
+        def stdout_notification(self, type, notifying_object, out_string=None):
+            self.writeStdOut(out_string)
+    
+If everything works, the Interpreter will (according to its published API)
+fire a notification via the
+:data:`IPython.kernel.core.notification.sharedCenter` of type
+:const:`STD_OUT_NOTIFICATION_TYPE` before writing anything to stdout [it's up
+to the Intereter implementation to figure out when to do this]. The
+notificaiton center will then call the registered callbacks for that event
+type (in this case, Dwight's frontend's stdout_notification method). Again,
+according to its API, the Interpreter provides an additional keyword argument
+when firing the notificaiton of out_string, a copy of the string it will write
+to stdout.
+
+Like magic, Dwight's frontend is able to provide output, even during
+long-running calculations. Now if Jim could just convince Dwight to use
+Twisted...
+
+    2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is stuck in the stone age, his frontend will be written in a new Fortran-like dialect of python and will run only from the command line. Because he doesn't need any fancy notification system and is used to worrying about every cycle on his rat-wheel powered mini, Boss Hog is adamant that the new notification system not produce any performance penalty. As they say in Hazard county, there's no such thing as a free lunch. If he wanted zero overhead, he should have kept using IPython 0.8. Instead, those tricky Duke boys slide in a suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module that imparts only a constant (and small) performance penalty when the Interpreter (or any other object) fires an event for which there are no registered observers. Of course, the same notificaiton-enabled Interpreter can then be used in frontends that require notifications, thus saving the IPython project from a nasty civil war.
+    
+    3. Barry is wrting a frontend for the IPython project. Because Barry's front end is the *new hotness*, it uses an asynchronous event model to communicate with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the :mod:`IPython.kernel.core.notification` module, Barry's frontend can register for notifications from the interpreter that are delivered asynchronously. Even if Barry's frontend is running on a separate process or even host from the Interpreter, the notifications are delivered, as if by dark and twisted magic. Just like Dwight's frontend, Barry's frontend can now recieve notifications of e.g. writing to stdout/stderr, opening/closing an external file, an exception in the executing code, etc.
  No newline at end of file

docs/source/development/roadmap.txt

@@ -1,96 +1,81
 .. _roadmap:
 
 ===================
 Development roadmap
 ===================
 
-.. contents::
-
 IPython is an ambitious project that is still under heavy development.  However, we want IPython to become useful to as many people as possible, as quickly as possible.  To help us accomplish this, we are laying out a roadmap of where we are headed and what needs to happen to get there.  Hopefully, this will help the IPython developers figure out the best things to work on for each upcoming release.
 
-Speaking of releases, we are going to begin releasing a new version of IPython every four weeks.  We are hoping that a regular release schedule, along with a clear roadmap of where we are headed will propel the project forward.
-
-Where are we headed
-===================
+Work targeted to particular releases
+====================================
 
-Our goal with IPython is simple: to provide a *powerful*, *robust* and *easy to use* framework for parallel computing.  While there are other secondary goals you will hear us talking about at various times, this is the primary goal of IPython that frames the roadmap.
+Release 0.10
+------------
 
-Steps along the way
-===================
+* Initial refactor of :command:`ipcluster`.
 
-Here we describe the various things that we need to work on to accomplish this goal.
+* Better TextMate integration.
 
-Setting up for regular release schedule
----------------------------------------
+* Merge in the daemon branch.
 
-We would like to begin to release IPython regularly (probably a 4 week release cycle).  To get ready for this, we need to revisit the development guidelines and put in information about releasing IPython.  
+Release 0.11
+------------
 
-Process startup and management
-------------------------------
+* Refactor the configuration system and command line options for
+  :command:`ipengine` and :command:`ipcontroller`. This will include the
+  creation of cluster directories that encapsulate all the configuration
+  files, log files and security related files for a particular cluster.
 
-IPython is implemented using a distributed set of processes that communicate using TCP/IP network channels.  Currently, users have to start each of the various processes separately using command line scripts.  This is both difficult and error prone.  Furthermore, there are a number of things that often need to be managed once the processes have been started, such as the sending of signals and the shutting down and cleaning up of processes.
+* Refactor :command:`ipcluster` to support the new configuration system.
 
-We need to build a system that makes it trivial for users to start and manage IPython processes.  This system should have the following properties:
+* Refactor the daemon stuff to support the new configuration system.
 
-	* It should possible to do everything through an extremely simple API that users
-	  can call from their own Python script.  No shell commands should be needed.
-	* This simple API should be configured using standard .ini files.
-	* The system should make it possible to start processes using a number of different
-	  approaches:  SSH, PBS/Torque, Xgrid, Windows Server, mpirun, etc.
-	* The controller and engine processes should each have a daemon for monitoring, 
-	  signaling and clean up.
-	* The system should be secure.
-	* The system should work under all the major operating systems, including
-	  Windows.
+* Merge back in the core of the notebook.
 
-Initial work has begun on the daemon infrastructure, and some of the needed logic is contained in the ipcluster script.
+Release 0.12
+------------
 
-Ease of use/high-level approaches to parallelism
-------------------------------------------------
+* Fully integrate process startup with the daemons for full process 
+  management.
 
-While our current API for clients is well designed, we can still do a lot better in designing a user-facing API that is super simple.  The main goal here is that it should take *almost no extra code* for users to get their code running in parallel.  For this to be possible, we need to tie into Python's standard idioms that enable efficient coding.  The biggest ones we are looking at are using context managers (i.e., Python 2.5's ``with`` statement) and decorators.  Initial work on this front has begun, but more work is needed.
+* Make the capabilites of :command:`ipcluster` available from simple Python 
+  classes.
 
-We also need to think about new models for expressing parallelism.  This is fun work as most of the foundation has already been established.
+Major areas of work
+===================
 
-Security
---------
+Refactoring the main IPython core
+---------------------------------
 
-Currently, IPython has no built in security or security model.  Because we would like IPython to be usable on public computer systems and over wide area networks, we need to come up with a robust solution for security.  Here are some of the specific things that need to be included:
+Process management for :mod:`IPython.kernel`
+--------------------------------------------
 
-	* User authentication between all processes (engines, controller and clients).
-	* Optional TSL/SSL based encryption of all communication channels.
-	* A good way of picking network ports so multiple users on the same system can
-	  run their own controller and engines without interfering with those of others.
-	* A clear model for security that enables users to evaluate the security risks
-	  associated with using IPython in various manners.
+Configuration system
+--------------------
 
-For the implementation of this, we plan on using Twisted's support for SSL and authentication.  One things that we really should look at is the `Foolscap`_ network protocol, which provides many of these things out of the box.
+Performance problems
+--------------------
 
-.. _Foolscap: http://foolscap.lothar.com/trac
+Currently, we have a number of performance issues that are waiting to bite users:
 
-The security work needs to be done in conjunction with other network protocol stuff.
+* The controller stores a large amount of state in Python dictionaries. Under
+  heavy usage, these dicts with get very large, causing memory usage problems.
+  We need to develop more scalable solutions to this problem, such as using a
+  sqlite database to store this state. This will also help the controller to
+  be more fault tolerant.
 
-Latent performance issues
--------------------------
+* We currently don't have a good way of handling large objects in the
+  controller. The biggest problem is that because we don't have any way of
+  streaming objects, we get lots of temporary copies in the low-level buffers.
+  We need to implement a better serialization approach and true streaming
+  support.
 
-Currently, we have a number of performance issues that are waiting to bite users:
+* The controller currently unpickles and repickles objects. We need to use the
+  [push|pull]_serialized methods instead.
 
-	* The controller store a large amount of state in Python dictionaries.  Under heavy
-	  usage, these dicts with get very large, causing memory usage problems.  We need to 
-	  develop more scalable solutions to this problem, such as using a sqlite database
-	  to store this state.  This will also help the controller to be more fault tolerant.
-	* Currently, the client to controller connections are done through XML-RPC using 
-	  HTTP 1.0.  This is very inefficient as XML-RPC is a very verbose protocol and 
-	  each request must be handled with a new connection.  We need to move these network
-	  connections over to PB or Foolscap.
-	* We currently don't have a good way of handling large objects in the controller.
-	  The biggest problem is that because we don't have any way of streaming objects,
-	  we get lots of temporary copies in the low-level buffers.  We need to implement
-	  a better serialization approach and true streaming support.
-	* The controller currently unpickles and repickles objects.  We need to use the 
-	  [push|pull]_serialized methods instead.
-	* Currently the controller is a bottleneck.  We need the ability to scale the 
-	  controller by aggregating multiple controllers into one effective controller.
+* Currently the controller is a bottleneck. The best approach for this is to
+  separate the controller itself into multiple processes, one for the core
+  controller and one each for the controller interfaces.
 
 
 

docs/source/faq.txt

@@ -1,93 +1,105
 .. _faq:
 
 ========================================
 Frequently asked questions
 ========================================
 
 General questions
 =================
 
 Questions about parallel computing with IPython
 ================================================
 
 Will IPython speed my Python code up?
 --------------------------------------
 
 Yes and no. When converting a serial code to run in parallel, there often many
 difficulty questions that need to be answered, such as:
 
-	* How should data be decomposed onto the set of processors?
-	* What are the data movement patterns?
-	* Can the algorithm be structured to minimize data movement?
-	* Is dynamic load balancing important?
+* How should data be decomposed onto the set of processors?
+
+* What are the data movement patterns?
+
+* Can the algorithm be structured to minimize data movement?
+
+* Is dynamic load balancing important?
 
 We can't answer such questions for you. This is the hard (but fun) work of parallel
 computing. But, once you understand these things IPython will make it easier for you to
 implement a good solution quickly. Most importantly, you will be able to use the
 resulting parallel code interactively.
 
 With that said, if your problem is trivial to parallelize, IPython has a number of
 different interfaces that will enable you to parallelize things is almost no time at
-all.  A good place to start is the ``map`` method of our `multiengine interface`_.
-
-.. _multiengine interface: ./parallel_multiengine
+all.  A good place to start is the ``map`` method of our :class:`MultiEngineClient`.
 
 What is the best way to use MPI from Python?
 --------------------------------------------
 
 What about all the other parallel computing packages in Python?
 ---------------------------------------------------------------
 
 Some of the unique characteristic of IPython are:
 
-	* IPython is the only architecture that abstracts out the notion of a 
-	  parallel computation in such a way that new models of parallel computing
-	  can be explored quickly and easily.  If you don't like the models we
-	  provide, you can simply create your own using the capabilities we provide.
-	* IPython is asynchronous from the ground up (we use `Twisted`_).
-	* IPython's architecture is designed to avoid subtle problems 
-	  that emerge because of Python's global interpreter lock (GIL).
-	* While IPython'1 architecture is designed to support a wide range
-	  of novel parallel computing models, it is fully interoperable with
-	  traditional MPI applications.
-	* IPython has been used and tested extensively on modern supercomputers.
-	* IPython's networking layers are completely modular.  Thus, is 
-	  straightforward to replace our existing network protocols with 
-	  high performance alternatives (ones based upon Myranet/Infiniband).
-	* IPython is designed from the ground up to support collaborative
-	  parallel computing.  This enables multiple users to actively develop
-	  and run the *same* parallel computation.
-	* Interactivity is a central goal for us.  While IPython does not have
-	  to be used interactivly, is can be.
-	  
+* IPython is the only architecture that abstracts out the notion of a 
+  parallel computation in such a way that new models of parallel computing
+  can be explored quickly and easily.  If you don't like the models we
+  provide, you can simply create your own using the capabilities we provide.
+  
+* IPython is asynchronous from the ground up (we use `Twisted`_).
+
+* IPython's architecture is designed to avoid subtle problems 
+  that emerge because of Python's global interpreter lock (GIL).
+  
+* While IPython's architecture is designed to support a wide range
+  of novel parallel computing models, it is fully interoperable with
+  traditional MPI applications.
+  
+* IPython has been used and tested extensively on modern supercomputers.
+
+* IPython's networking layers are completely modular.  Thus, is 
+  straightforward to replace our existing network protocols with 
+  high performance alternatives (ones based upon Myranet/Infiniband).
+  
+* IPython is designed from the ground up to support collaborative
+  parallel computing.  This enables multiple users to actively develop
+  and run the *same* parallel computation.
+  
+* Interactivity is a central goal for us.  While IPython does not have
+  to be used interactivly, it can be.
+      
 .. _Twisted: http://www.twistedmatrix.com
 
 Why The IPython controller a bottleneck in my parallel calculation?
 -------------------------------------------------------------------
 
 A golden rule in parallel computing is that you should only move data around if you
 absolutely need to. The main reason that the controller becomes a bottleneck is that
 too much data is being pushed and pulled to and from the engines. If your algorithm
 is structured in this way, you really should think about alternative ways of
 handling the data movement. Here are some ideas:
 
-	1. Have the engines write data to files on the locals disks of the engines.
-	2. Have the engines write data to files on a file system that is shared by
-	   the engines.
-	3. Have the engines write data to a database that is shared by the engines.
-	4. Simply keep data in the persistent memory of the engines and move the
-	   computation to the data (rather than the data to the computation).
-	5. See if you can pass data directly between engines using MPI.
+1. Have the engines write data to files on the locals disks of the engines.
+
+2. Have the engines write data to files on a file system that is shared by
+   the engines.
+
+3. Have the engines write data to a database that is shared by the engines.
+
+4. Simply keep data in the persistent memory of the engines and move the
+   computation to the data (rather than the data to the computation).
+
+5. See if you can pass data directly between engines using MPI.
 
 Isn't Python slow to be used for high-performance parallel computing?
 ---------------------------------------------------------------------
 
 
 
 
  
 
 
 
 
 

docs/source/history.txt

@@ -1,56 +1,38
 .. _history:
 
 =======
 History
 =======
 
 Origins
 =======
 
-The current IPython system grew out of the following three projects:
-
-    * [ipython] by Fernando Pérez. I was working on adding
-      Mathematica-type prompts and a flexible configuration system
-      (something better than $PYTHONSTARTUP) to the standard Python
-      interactive interpreter.
-    * [IPP] by Janko Hauser. Very well organized, great usability. Had
-      an old help system. IPP was used as the 'container' code into
-      which I added the functionality from ipython and LazyPython.
-    * [LazyPython] by Nathan Gray. Simple but very powerful. The quick
-      syntax (auto parens, auto quotes) and verbose/colored tracebacks
-      were all taken from here.
-
-When I found out about IPP and LazyPython I tried to join all three
-into a unified system. I thought this could provide a very nice
-working environment, both for regular programming and scientific
-computing: shell-like features, IDL/Matlab numerics, Mathematica-type
-prompt history and great object introspection and help facilities. I
-think it worked reasonably well, though it was a lot more work than I
-had initially planned.
-
-
-Current status
-==============
-
-The above listed features work, and quite well for the most part. But
-until a major internal restructuring is done (see below), only bug
-fixing will be done, no other features will be added (unless very minor
-and well localized in the cleaner parts of the code).
-
-IPython consists of some 18000 lines of pure python code, of which
-roughly two thirds is reasonably clean. The rest is, messy code which
-needs a massive restructuring before any further major work is done.
-Even the messy code is fairly well documented though, and most of the
-problems in the (non-existent) class design are well pointed to by a
-PyChecker run. So the rewriting work isn't that bad, it will just be
-time-consuming.
-
-
-Future
-------
-
-See the separate new_design document for details. Ultimately, I would
-like to see IPython become part of the standard Python distribution as a
-'big brother with batteries' to the standard Python interactive
-interpreter. But that will never happen with the current state of the
-code, so all contributions are welcome.
  No newline at end of file
+IPython was starting in 2001 by Fernando Perez.  IPython as we know it
+today grew out of the following three projects:
+
+* ipython by Fernando Pérez. I was working on adding
+  Mathematica-type prompts and a flexible configuration system
+  (something better than $PYTHONSTARTUP) to the standard Python
+  interactive interpreter.
+* IPP by Janko Hauser. Very well organized, great usability. Had
+  an old help system. IPP was used as the 'container' code into
+  which I added the functionality from ipython and LazyPython.
+* LazyPython by Nathan Gray. Simple but very powerful. The quick
+  syntax (auto parens, auto quotes) and verbose/colored tracebacks
+  were all taken from here.
+
+Here is how Fernando describes it:
+
+    When I found out about IPP and LazyPython I tried to join all three
+    into a unified system. I thought this could provide a very nice
+    working environment, both for regular programming and scientific
+    computing: shell-like features, IDL/Matlab numerics, Mathematica-type
+    prompt history and great object introspection and help facilities. I
+    think it worked reasonably well, though it was a lot more work than I
+    had initially planned.
+
+Today and how we got here
+=========================
+
+This needs to be filled in.
+

docs/source/index.txt

@@ -1,28 +1,30
 =====================
 IPython Documentation
 =====================
 
-Contents
-========
+.. htmlonly::
+
+   :Release: |release|
+   :Date: |today|
+
+   Contents:
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    overview.txt
    install/index.txt
    interactive/index.txt
    parallel/index.txt
    config/index.txt
    changes.txt
    development/index.txt
    faq.txt
    history.txt
    license_and_copyright.txt
    credits.txt
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
  No newline at end of file
+.. htmlonly::
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

docs/source/install/index.txt

@@ -1,11 +1,10
 .. _install_index:
 
 ==================
 Installation
 ==================
 
 .. toctree::
    :maxdepth: 2
 
-   basic.txt
-   advanced.txt
+   install.txt

docs/source/interactive/index.txt

@@ -1,11 +1,11
 ==================================
 Using IPython for interactive work
 ==================================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    tutorial.txt
    reference.txt
    shell.txt
    extension_api.txt

docs/source/interactive/reference.txt

@@ -1,3163 +1,3194
-.. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root 'toctree' directive.
-
 =================
 IPython reference
 =================
 
-.. contents::
-
-.. _Command line options:
+.. _command_line_options:
 
 Command-line usage
 ==================
 
 You start IPython with the command::
 
     $ ipython [options] files
 
 If invoked with no options, it executes all the files listed in sequence
 and drops you into the interpreter while still acknowledging any options
 you may have set in your ipythonrc file. This behavior is different from
 standard Python, which when called as python -i will only execute one
 file and ignore your configuration setup.
 
 Please note that some of the configuration options are not available at
 the command line, simply because they are not practical here. Look into
 your ipythonrc configuration file for details on those. This file
 typically installed in the $HOME/.ipython directory. For Windows users,
 $HOME resolves to C:\\Documents and Settings\\YourUserName in most
 instances. In the rest of this text, we will refer to this directory as
 IPYTHONDIR.
 
 .. _Threading options:
 
 
 Special Threading Options
 -------------------------
 
 The following special options are ONLY valid at the beginning of the
 command line, and not later. This is because they control the initial-
 ization of ipython itself, before the normal option-handling mechanism
 is active.
 
     -gthread, -qthread, -q4thread, -wthread, -pylab: 
 	Only one of these can be given, and it can only be given as
 	the first option passed to IPython (it will have no effect in
 	any other position).  They provide threading support for the
 	GTK, Qt (versions 3 and 4) and WXPython toolkits, and for the
 	matplotlib library.
 
 	With any of the first four options, IPython starts running a
 	separate thread for the graphical toolkit's operation, so that
 	you can open and control graphical elements from within an
 	IPython command line, without blocking. All four provide
 	essentially the same functionality, respectively for GTK, Qt3,
 	Qt4 and WXWidgets (via their Python interfaces).
 
 	Note that with -wthread, you can additionally use the
 	-wxversion option to request a specific version of wx to be
 	used.  This requires that you have the wxversion Python module
 	installed, which is part of recent wxPython distributions.
 
 	If -pylab is given, IPython loads special support for the mat
 	plotlib library (http://matplotlib.sourceforge.net), allowing
 	interactive usage of any of its backends as defined in the
 	user's ~/.matplotlib/matplotlibrc file. It automatically
 	activates GTK, Qt or WX threading for IPyhton if the choice of
 	matplotlib backend requires it. It also modifies the %run
 	command to correctly execute (without blocking) any
 	matplotlib-based script which calls show() at the end.
 
     -tk
 	The -g/q/q4/wthread options, and -pylab (if matplotlib is
 	configured to use GTK, Qt3, Qt4 or WX), will normally block Tk
 	graphical interfaces. This means that when either GTK, Qt or WX
 	threading is active, any attempt to open a Tk GUI will result in a
 	dead window, and possibly cause the Python interpreter to crash.
 	An extra option, -tk, is available to address this issue. It can
 	only be given as a second option after any of the above (-gthread,
 	-wthread or -pylab).
 
 	If -tk is given, IPython will try to coordinate Tk threading
 	with GTK, Qt or WX. This is however potentially unreliable, and
 	you will have to test on your platform and Python configuration to
 	determine whether it works for you. Debian users have reported
 	success, apparently due to the fact that Debian builds all of Tcl,
 	Tk, Tkinter and Python with pthreads support. Under other Linux
 	environments (such as Fedora Core 2/3), this option has caused
 	random crashes and lockups of the Python interpreter. Under other
 	operating systems (Mac OSX and Windows), you'll need to try it to
 	find out, since currently no user reports are available.
     
 	There is unfortunately no way for IPython to determine at run time
 	whether -tk will work reliably or not, so you will need to do some
 	experiments before relying on it for regular work.
 
 
 
 Regular Options
 ---------------
 
 After the above threading options have been given, regular options can
 follow in any order. All options can be abbreviated to their shortest
 non-ambiguous form and are case-sensitive. One or two dashes can be
 used. Some options have an alternate short form, indicated after a ``|``.
 
 Most options can also be set from your ipythonrc configuration file. See
 the provided example for more details on what the options do. Options
 given at the command line override the values set in the ipythonrc file.
 
 All options with a [no] prepended can be specified in negated form
 (-nooption instead of -option) to turn the feature off.
 
     -help  print a help message and exit.
 
     -pylab
 	this can only be given as the first option passed to IPython
 	(it will have no effect in any other position). It adds
 	special support for the matplotlib library
 	(http://matplotlib.sourceforge.ne), allowing interactive usage
 	of any of its backends as defined in the user's .matplotlibrc
 	file.  It automatically activates GTK or WX threading for
 	IPyhton if the choice of matplotlib backend requires it. It
 	also modifies the %run command to correctly execute (without
 	blocking) any matplotlib-based script which calls show() at
 	the end. See `Matplotlib support`_ for more details.
 
     -autocall <val>
 	Make IPython automatically call any callable object even if you
 	didn't type explicit parentheses. For example, 'str 43' becomes
 	'str(43)' automatically. The value can be '0' to disable the feature,
 	'1' for smart autocall, where it is not applied if there are no more
 	arguments on the line, and '2' for full autocall, where all callable
 	objects are automatically called (even if no arguments are
 	present). The default is '1'.
 
     -[no]autoindent    
 	Turn automatic indentation on/off.
 
     -[no]automagic 
 	make magic commands automatic (without needing their first character
 	to be %). Type %magic at the IPython prompt for more information.
 
     -[no]autoedit_syntax 
 	When a syntax error occurs after editing a file, automatically
 	open the file to the trouble causing line for convenient
 	fixing.
 
     -[no]banner		Print the initial information banner (default on).
 
     -c <command>
 	execute the given command string. This is similar to the -c
 	option in the normal Python interpreter.
 
     -cache_size, cs <n> 
 	size of the output cache (maximum number of entries to hold in
 	memory). The default is 1000, you can change it permanently in your
 	config file. Setting it to 0 completely disables the caching system,
 	and the minimum value accepted is 20 (if you provide a value less than
 	20, it is reset to 0 and a warning is issued) This limit is defined
 	because otherwise you'll spend more time re-flushing a too small cache
 	than working.
 
     -classic, cl 
 	Gives IPython a similar feel to the classic Python
 	prompt.
 
     -colors <scheme> 
 	Color scheme for prompts and exception reporting. Currently
 	implemented: NoColor, Linux and LightBG.
 
     -[no]color_info 
 	IPython can display information about objects via a set of functions,
 	and optionally can use colors for this, syntax highlighting source
 	code and various other elements.  However, because this information is
 	passed through a pager (like 'less') and many pagers get confused with
 	color codes, this option is off by default. You can test it and turn
 	it on permanently in your ipythonrc file if it works for you. As a
 	reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
 	that in RedHat 7.2 doesn't.
 
 	Test it and turn it on permanently if it works with your
 	system. The magic function %color_info allows you to toggle this
 	interactively for testing.
 
     -[no]debug 
 	Show information about the loading process. Very useful to pin down
 	problems with your configuration files or to get details about
 	session restores.
 
     -[no]deep_reload: 
 	IPython can use the deep_reload module which reloads changes in
 	modules recursively (it replaces the reload() function, so you don't
 	need to change anything to use it).  deep_reload() forces a full
 	reload of modules whose code may have changed, which the default
 	reload() function does not.
 
 	When deep_reload is off, IPython will use the normal reload(),
 	but deep_reload will still be available as dreload(). This
 	feature is off by default [which means that you have both
 	normal reload() and dreload()].
 
     -editor <name>
 	Which editor to use with the %edit command. By default,
 	IPython will honor your EDITOR environment variable (if not
 	set, vi is the Unix default and notepad the Windows one).
 	Since this editor is invoked on the fly by IPython and is
 	meant for editing small code snippets, you may want to use a
 	small, lightweight editor here (in case your default EDITOR is
 	something like Emacs).
 
     -ipythondir <name> 
 	name of your IPython configuration directory IPYTHONDIR. This
 	can also be specified through the environment variable
 	IPYTHONDIR.
 
     -log, l 
 	generate a log file of all input. The file is named
 	ipython_log.py in your current directory (which prevents logs
 	from multiple IPython sessions from trampling each other). You
 	can use this to later restore a session by loading your
 	logfile as a file to be executed with option -logplay (see
 	below).
 
     -logfile, lf <name>   specify the name of your logfile.
 
     -logplay, lp <name> 
 
       you can replay a previous log. For restoring a session as close as
       possible to the state you left it in, use this option (don't just run
       the logfile). With -logplay, IPython will try to reconstruct the
       previous working environment in full, not just execute the commands in
       the logfile.
 
       When a session is restored, logging is automatically turned on
       again with the name of the logfile it was invoked with (it is
       read from the log header). So once you've turned logging on for
       a session, you can quit IPython and reload it as many times as
       you want and it will continue to log its history and restore
       from the beginning every time.
       
       Caveats: there are limitations in this option. The history
       variables _i*,_* and _dh don't get restored properly. In the
       future we will try to implement full session saving by writing
       and retrieving a 'snapshot' of the memory state of IPython. But
       our first attempts failed because of inherent limitations of
       Python's Pickle module, so this may have to wait.
 
     -[no]messages   
 	Print messages which IPython collects about its startup
 	process (default on).
 
     -[no]pdb
 	Automatically call the pdb debugger after every uncaught
 	exception. If you are used to debugging using pdb, this puts
 	you automatically inside of it after any call (either in
 	IPython or in code called by it) which triggers an exception
 	which goes uncaught.
 
     -pydb
 	Makes IPython use the third party "pydb" package as debugger,
 	instead of pdb. Requires that pydb is installed.
 	
     -[no]pprint
 	ipython can optionally use the pprint (pretty printer) module
 	for displaying results. pprint tends to give a nicer display
 	of nested data structures. If you like it, you can turn it on
 	permanently in your config file (default off).
 
     -profile, p <name>
 
 	assume that your config file is ipythonrc-<name> or
 	ipy_profile_<name>.py (looks in current dir first, then in
 	IPYTHONDIR).  This is a quick way to keep and load multiple
 	config files for different tasks, especially if you use the
 	include option of config files. You can keep a basic
 	IPYTHONDIR/ipythonrc file and then have other 'profiles' which
 	include this one and load extra things for particular
 	tasks. For example:
 
 	1. $HOME/.ipython/ipythonrc : load basic things you always want.
 	2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
 	3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
 
 	Since it is possible to create an endless loop by having
 	circular file inclusions, IPython will stop if it reaches 15
 	recursive inclusions.
 
     -prompt_in1, pi1 <string>
-	Specify the string used for input prompts. Note that if you
-	are using numbered prompts, the number is represented with a
-	'\#' in the string. Don't forget to quote strings with spaces
-	embedded in them. Default: 'In [\#]:'.  Sec. Prompts_
-	discusses in detail all the available escapes to customize
-	your prompts.
+
+        Specify the string used for input prompts. Note that if you are using
+	numbered prompts, the number is represented with a '\#' in the
+	string. Don't forget to quote strings with spaces embedded in
+	them. Default: 'In [\#]:'.  The :ref:`prompts section <prompts>`
+	discusses in detail all the available escapes to customize your
+	prompts.
 
     -prompt_in2, pi2 <string>
 	Similar to the previous option, but used for the continuation
 	prompts. The special sequence '\D' is similar to '\#', but
 	with all digits replaced dots (so you can have your
 	continuation prompt aligned with your input prompt).  Default:
 	' .\D.:' (note three spaces at the start for alignment with
 	'In [\#]').
 
     -prompt_out,po <string> 
 	String used for output prompts, also uses numbers like
 	prompt_in1. Default: 'Out[\#]:'
 
     -quick   start in bare bones mode (no config file loaded).
 
     -rcfile <name>   
 	name of your IPython resource configuration file. Normally
 	IPython loads ipythonrc (from current directory) or
 	IPYTHONDIR/ipythonrc.
 
 	If the loading of your config file fails, IPython starts with
 	a bare bones configuration (no modules loaded at all).
 
     -[no]readline
 	use the readline library, which is needed to support name
 	completion and command history, among other things.  It is
 	enabled by default, but may cause problems for users of
 	X/Emacs in Python comint or shell buffers.
 
 	Note that X/Emacs 'eterm' buffers (opened with M-x term) support
 	IPython's readline and syntax coloring fine, only 'emacs' (M-x
 	shell and C-c !) buffers do not.
 
     -screen_length, sl <n>
 	number of lines of your screen. This is used to control
 	printing of very long strings. Strings longer than this number
 	of lines will be sent through a pager instead of directly
 	printed.
 
 	The default value for this is 0, which means IPython will
 	auto-detect your screen size every time it needs to print certain
 	potentially long strings (this doesn't change the behavior of the
 	'print' keyword, it's only triggered internally). If for some
 	reason this isn't working well (it needs curses support), specify
 	it yourself. Otherwise don't change the default.
 
     -separate_in, si <string>
 
 	separator before input prompts.
 	Default: '\n'
 
     -separate_out, so <string>  
         separator before output prompts.
         Default: nothing.
 
     -separate_out2, so2
 	separator after output prompts.
 	Default: nothing.
 	For these three options, use the value 0 to specify no separator.
 
     -nosep   
 	shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
 	0'. Simply removes all input/output separators.
 
     -upgrade 
 	allows you to upgrade your IPYTHONDIR configuration when you
 	install a new version of IPython. Since new versions may
 	include new command line options or example files, this copies
 	updated ipythonrc-type files. However, it backs up (with a
 	.old extension) all files which it overwrites so that you can
 	merge back any customizations you might have in your personal
 	files. Note that you should probably use %upgrade instead,
 	it's a safer alternative.
 
 
     -Version    print version information and exit.
 
     -wxversion <string> 
 	Select a specific version of wxPython (used in conjunction
 	with -wthread). Requires the wxversion module, part of recent
 	wxPython distributions
 
     -xmode <modename>
 
 	Mode for exception reporting.
 
 	Valid modes: Plain, Context and Verbose.
 
 	* Plain: similar to python's normal traceback printing.
 	* Context: prints 5 lines of context source code around each
 	  line in the traceback.
 	* Verbose: similar to Context, but additionally 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).
 
 Interactive use
 ===============
 
 Warning: IPython relies on the existence of a global variable called
 _ip which controls the shell itself. If you redefine _ip to anything,
 bizarre behavior will quickly occur.
 
 Other than the above warning, IPython is meant to work as a drop-in
 replacement for the standard interactive interpreter. As such, any code
 which is valid python should execute normally under IPython (cases where
 this is not true should be reported as bugs). It does, however, offer
 many features which are not available at a standard python prompt. What
 follows is a list of these.
 
 
 Caution for Windows users
 -------------------------
 
 Windows, unfortunately, uses the '\' character as a path
 separator. This is a terrible choice, because '\' also represents the
 escape character in most modern programming languages, including
 Python. For this reason, using '/' character is recommended if you
 have problems with ``\``.  However, in Windows commands '/' flags
 options, so you can not use it for the root directory. This means that
 paths beginning at the root must be typed in a contrived manner like:
 ``%copy \opt/foo/bar.txt \tmp``
 
 .. _magic:
 
 Magic command system
 --------------------
 
 IPython will treat any line whose first character is a % as a special
 call to a 'magic' function. These allow you to control the behavior of
 IPython itself, plus a lot of system-type features. They are all
 prefixed with a % character, but parameters are given without
 parentheses or quotes.
 
 Example: typing '%cd mydir' (without the quotes) changes you working
 directory to 'mydir', if it exists.
 
 If you have 'automagic' enabled (in your ipythonrc file, via the command
 line option -automagic or with the %automagic function), you don't need
 to type in the % explicitly. IPython will scan its internal list of
 magic functions and call one if it exists. With automagic on you can
 then just type 'cd mydir' to go to directory 'mydir'. The automagic
 system has the lowest possible precedence in name searches, so defining
 an identifier with the same name as an existing magic function will
 shadow it for automagic use. You can still access the shadowed magic
 function by explicitly using the % character at the beginning of the line.
 
 An example (with automagic on) should clarify all this::
 
     In [1]: cd ipython # %cd is called by automagic
 
     /home/fperez/ipython
 
     In [2]: cd=1 # now cd is just a variable
 
     In [3]: cd .. # and doesn't work as a function anymore
 
     ------------------------------
 
         File "<console>", line 1
 
           cd ..
 
               ^
 
     SyntaxError: invalid syntax
 
     In [4]: %cd .. # but %cd always works
 
     /home/fperez
 
     In [5]: del cd # if you remove the cd variable
 
     In [6]: cd ipython # automagic can work again
 
     /home/fperez/ipython
 
 You can define your own magic functions to extend the system. The
 following example defines a new magic command, %impall::
 
     import IPython.ipapi 
 
     ip = IPython.ipapi.get()
 
     def doimp(self, arg):
 
         ip = self.api
 
         ip.ex("import %s; reload(%s); from %s import *" % (
 
         arg,arg,arg)
 
         )
 
     ip.expose_magic('impall', doimp)
 
 You can also define your own aliased names for magic functions. In your
 ipythonrc file, placing a line like:
 
 execute __IP.magic_cl = __IP.magic_clear
 
 will define %cl as a new name for %clear.
 
 Type %magic for more information, including a list of all available
 magic functions at any time and their docstrings. You can also type
 %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
 information on the '?' system) to get information about any particular
 magic function you are interested in.
 
 
 Magic commands
 --------------
 
 The rest of this section is automatically generated for each release
 from the docstrings in the IPython code. Therefore the formatting is
 somewhat minimal, but this method has the advantage of having
 information always in sync with the code.
 
 A list of all the magic commands available in IPython's default
 installation follows. This is similar to what you'll see by simply
 typing %magic at the prompt, but that will also give you information
 about magic commands you may have added as part of your personal
 customizations.
 
 .. magic_start
 
 **%Exit**::
 
 	Exit IPython without confirmation.
 
 **%Pprint**::
 
 	Toggle pretty printing on/off.
 
 **%alias**::
 
 	Define an alias for a system command.
 
         '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
         Then, typing 'alias_name params' will execute the system command 'cmd
         params' (from your underlying operating system).
 
         Aliases have lower precedence than magic functions and Python normal
         variables, so if 'foo' is both a Python variable and an alias, the
         alias can not be executed until 'del foo' removes the Python variable.
 
         You can use the %l specifier in an alias definition to represent the
         whole line when the alias is called.  For example:
 
           In [2]: alias all echo "Input in brackets: <%l>"\
           In [3]: all hello world\
           Input in brackets: <hello world>
 
         You can also define aliases with parameters using %s specifiers (one
         per parameter):
         
           In [1]: alias parts echo first %s second %s\
           In [2]: %parts A B\
           first A second B\
           In [3]: %parts A\
           Incorrect number of arguments: 2 expected.\
           parts is an alias to: 'echo first %s second %s'
 
         Note that %l and %s are mutually exclusive.  You can only use one or
         the other in your aliases.
 
         Aliases expand Python variables just like system calls using ! or !! 
         do: all expressions prefixed with '$' get expanded.  For details of
         the semantic rules, see PEP-215:
         http://www.python.org/peps/pep-0215.html.  This is the library used by
         IPython for variable expansion.  If you want to access a true shell
         variable, an extra $ is necessary to prevent its expansion by IPython:
 
         In [6]: alias show echo\
         In [7]: PATH='A Python string'\
         In [8]: show $PATH\
         A Python string\
         In [9]: show $$PATH\
         /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
 
         You can use the alias facility to acess all of $PATH.  See the %rehash
         and %rehashx functions, which automatically create aliases for the
         contents of your $PATH.
 
         If called with no parameters, %alias prints the current alias table.
 
 **%autocall**::
 
 	Make functions callable without having to type parentheses.
 
         Usage:
 
            %autocall [mode]
 
         The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
         value is toggled on and off (remembering the previous state).
 
         In more detail, these values mean:
 
         0 -> fully disabled
 
         1 -> active, but do not apply if there are no arguments on the line.
 
         In this mode, you get:
 
         In [1]: callable
         Out[1]: <built-in function callable>
 
         In [2]: callable 'hello'
         ------> callable('hello')
         Out[2]: False
 
         2 -> Active always.  Even if no arguments are present, the callable
         object is called:
 
         In [4]: callable
         ------> callable()
 
         Note that even with autocall off, you can still use '/' at the start of
         a line to treat the first argument on the command line as a function
         and add parentheses to it:
 
         In [8]: /str 43
         ------> str(43)
         Out[8]: '43'
 
 **%autoindent**::
 
 	Toggle autoindent on/off (if available).
 
 **%automagic**::
 
 	Make magic functions callable without having to type the initial %.
 
         Without argumentsl toggles on/off (when off, you must call it as
         %automagic, of course).  With arguments it sets the value, and you can
         use any of (case insensitive):
 
          - on,1,True: to activate
 
          - off,0,False: to deactivate.
 
         Note that magic functions have lowest priority, so if there's a
         variable whose name collides with that of a magic fn, automagic won't
         work for that function (you get the variable instead). However, if you
         delete the variable (del var), the previously shadowed magic function
         becomes visible to automagic again.
 
 **%bg**::
 
 	Run a job in the background, in a separate thread.
 
         For example,
 
           %bg myfunc(x,y,z=1)
 
         will execute 'myfunc(x,y,z=1)' in a background thread.  As soon as the
         execution starts, a message will be printed indicating the job
         number.  If your job number is 5, you can use
 
           myvar = jobs.result(5)  or  myvar = jobs[5].result
 
         to assign this result to variable 'myvar'.
 
         IPython has a job manager, accessible via the 'jobs' object.  You can
         type jobs? to get more information about it, and use jobs.<TAB> to see
         its attributes.  All attributes not starting with an underscore are
         meant for public use.
 
         In particular, look at the jobs.new() method, which is used to create
         new jobs.  This magic %bg function is just a convenience wrapper
         around jobs.new(), for expression-based jobs.  If you want to create a
         new job with an explicit function object and arguments, you must call
         jobs.new() directly.
 
         The jobs.new docstring also describes in detail several important
         caveats associated with a thread-based model for background job
         execution.  Type jobs.new? for details.
 
         You can check the status of all jobs with jobs.status().
 
         The jobs variable is set by IPython into the Python builtin namespace.
         If you ever declare a variable named 'jobs', you will shadow this
         name.  You can either delete your global jobs variable to regain
         access to the job manager, or make a new name and assign it manually
         to the manager (stored in IPython's namespace).  For example, to
         assign the job manager to the Jobs name, use:
 
           Jobs = __builtins__.jobs
 
 **%bookmark**::
 
 	Manage IPython's bookmark system.
 
         %bookmark <name>       - set bookmark to current dir
         %bookmark <name> <dir> - set bookmark to <dir>
         %bookmark -l           - list all bookmarks
         %bookmark -d <name>    - remove bookmark
         %bookmark -r           - remove all bookmarks
 
         You can later on access a bookmarked folder with:
           %cd -b <name>
         or simply '%cd <name>' if there is no directory called <name> AND
         there is such a bookmark defined.
 
         Your bookmarks persist through IPython sessions, but they are
         associated with each profile.
 
 **%cd**::
 
 	Change the current working directory.
 
         This command automatically maintains an internal list of directories
         you visit during your IPython session, in the variable _dh. The
         command %dhist shows this history nicely formatted. You can also
         do 'cd -<tab>' to see directory history conveniently.
 
         Usage:
 
           cd 'dir': changes to directory 'dir'.
 
           cd -: changes to the last visited directory.
 
           cd -<n>: changes to the n-th directory in the directory history.
 
           cd -b <bookmark_name>: jump to a bookmark set by %bookmark
              (note: cd <bookmark_name> is enough if there is no
               directory <bookmark_name>, but a bookmark with the name exists.)
               'cd -b <tab>' allows you to tab-complete bookmark names. 
 
         Options:
 
         -q: quiet.  Do not print the working directory after the cd command is
         executed.  By default IPython's cd command does print this directory,
         since the default prompts do not display path information.
         
         Note that !cd doesn't work for this purpose because the shell where
         !command runs is immediately discarded after executing 'command'.
 
 **%clear**::
 
 	 Clear various data (e.g. stored history data)
     
     %clear out - clear output history
     %clear in  - clear input history
     %clear shadow_compress - Compresses shadow history (to speed up ipython)
     %clear shadow_nuke - permanently erase all entries in shadow history
     %clear dhist - clear dir history
 
 **%color_info**::
 
 	Toggle color_info.
 
         The color_info configuration parameter controls whether colors are
         used for displaying object details (by things like %psource, %pfile or
         the '?' system). This function toggles this value with each call.
 
         Note that unless you have a fairly recent pager (less works better
         than more) in your system, using colored object information displays
         will not work properly. Test it and see.
 
 **%colors**::
 
 	Switch color scheme for prompts, info system and exception handlers.
 
         Currently implemented schemes: NoColor, Linux, LightBG.
 
         Color scheme names are not case-sensitive.
 
 **%cpaste**::
 
 	Allows you to paste & execute a pre-formatted code block from clipboard
         
         You must terminate the block with '--' (two minus-signs) alone on the
         line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
         is the new sentinel for this operation)
         
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
         ignored, to allow pasting directly from e-mails or diff files. The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
         
         You can also pass a variable name as an argument, e.g. '%cpaste foo'.
         This assigns the pasted block to variable 'foo' as string, without 
         dedenting or executing it.
         
         Do not be alarmed by garbled output on Windows (it's a readline bug). 
         Just press enter and type -- (and press enter again) and the block 
         will be what was just pasted.
         
         IPython statements (magics, shell escapes) are not supported (yet).
 
 **%debug**::
 
 	Activate the interactive debugger in post-mortem mode.
 
         If an exception has just occurred, this lets you inspect its stack
         frames interactively.  Note that this will always work only on the last
         traceback that occurred, so you must call this quickly after an
         exception that you wish to inspect has fired, because if another one
         occurs, it clobbers the previous one.
 
         If you want IPython to automatically do this on every exception, see
         the %pdb magic for more details.
 
 **%dhist**::
 
 	Print your history of visited directories.
 
         %dhist       -> print full history\
         %dhist n     -> print last n entries only\
         %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
 
         This history is automatically maintained by the %cd command, and
         always available as the global list variable _dh. You can use %cd -<n>
         to go to directory number <n>.
         
         Note that most of time, you should view directory history by entering
         cd -<TAB>.
 
 **%dirs**::
 
 	Return the current directory stack.
 
 **%doctest_mode**::
 
 	Toggle doctest mode on and off.
 
         This mode allows you to toggle the prompt behavior between normal
         IPython prompts and ones that are as similar to the default IPython
         interpreter as possible.
 
         It also supports the pasting of code snippets that have leading '>>>'
         and '...' prompts in them.  This means that you can paste doctests from
         files or docstrings (even if they have leading whitespace), and the
         code will execute correctly.  You can then use '%history -tn' to see
         the translated history without line numbers; this will give you the
         input after removal of all the leading prompts and whitespace, which
         can be pasted back into an editor.
 
         With these features, you can switch into this mode easily whenever you
         need to do testing and changes to doctests, without having to leave
         your existing IPython session.
 
 **%ed**::
 
 	Alias to %edit.
 
 **%edit**::
 
 	Bring up an editor and execute the resulting code.
 
         Usage:
           %edit [options] [args]
 
         %edit runs IPython's editor hook.  The default version of this hook is
         set to call the __IPYTHON__.rc.editor command.  This is read from your
         environment variable $EDITOR.  If this isn't found, it will default to
         vi under Linux/Unix and to notepad under Windows.  See the end of this
         docstring for how to change the editor hook.
 
         You can also set the value of this editor via the command line option
         '-editor' or in your ipythonrc file. This is useful if you wish to use
         specifically for IPython an editor different from your typical default
         (and for Windows users who typically don't set environment variables).
 
         This command allows you to conveniently edit multi-line code right in
         your IPython session.
         
         If called without arguments, %edit opens up an empty editor with a
         temporary file and will execute the contents of this file when you
         close it (don't forget to save it!).
 
 
         Options:
 
         -n <number>: open the editor at a specified line number.  By default,
         the IPython editor hook uses the unix syntax 'editor +N filename', but
         you can configure this by providing your own modified hook if your
         favorite editor supports line-number specifications with a different
         syntax.
         
         -p: this will call the editor with the same data as the previous time
         it was used, regardless of how long ago (in your current session) it
         was.
 
         -r: use 'raw' input.  This option only applies to input taken from the
         user's history.  By default, the 'processed' history is used, so that
         magics are loaded in their transformed version to valid Python.  If
         this option is given, the raw input as typed as the command line is
         used instead.  When you exit the editor, it will be executed by
         IPython's own processor.
         
         -x: do not execute the edited code immediately upon exit. This is
         mainly useful if you are editing programs which need to be called with
         command line arguments, which you can then do using %run.
 
 
         Arguments:
 
         If arguments are given, the following possibilites exist:
 
         - The arguments are numbers or pairs of colon-separated numbers (like
         1 4:8 9). These are interpreted as lines of previous input to be
         loaded into the editor. The syntax is the same of the %macro command.
 
         - If the argument doesn't start with a number, it is evaluated as a
         variable and its contents loaded into the editor. You can thus edit
         any string which contains python code (including the result of
         previous edits).
 
         - If the argument is the name of an object (other than a string),
         IPython will try to locate the file where it was defined and open the
         editor at the point where it is defined. You can use `%edit function`
         to load an editor exactly at the point where 'function' is defined,
         edit it and have the file be executed automatically.
 
         If the object is a macro (see %macro for details), this opens up your
         specified editor with a temporary file containing the macro's data.
         Upon exit, the macro is reloaded with the contents of the file.
 
         Note: opening at an exact line is only supported under Unix, and some
         editors (like kedit and gedit up to Gnome 2.8) do not understand the
         '+NUMBER' parameter necessary for this feature. Good editors like
         (X)Emacs, vi, jed, pico and joe all do.
 
         - If the argument is not found as a variable, IPython will look for a
         file with that name (adding .py if necessary) and load it into the
         editor. It will execute its contents with execfile() when you exit,
         loading any code in the file into your interactive namespace.
 
         After executing your code, %edit will return as output the code you
         typed in the editor (except when it was an existing file). This way
         you can reload the code in further invocations of %edit as a variable,
         via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
         the output.
 
         Note that %edit is also available through the alias %ed.
 
         This is an example of creating a simple function inside the editor and
         then modifying it. First, start up the editor:
 
         In [1]: ed\
         Editing... done. Executing edited code...\
         Out[1]: 'def foo():\n    print "foo() was defined in an editing session"\n'
 
         We can then call the function foo():
         
         In [2]: foo()\
         foo() was defined in an editing session
 
         Now we edit foo.  IPython automatically loads the editor with the
         (temporary) file where foo() was previously defined:
         
         In [3]: ed foo\
         Editing... done. Executing edited code...
 
         And if we call foo() again we get the modified version:
         
         In [4]: foo()\
         foo() has now been changed!
 
         Here is an example of how to edit a code snippet successive
         times. First we call the editor:
 
         In [8]: ed\
         Editing... done. Executing edited code...\
         hello\
         Out[8]: "print 'hello'\n"
 
         Now we call it again with the previous output (stored in _):
 
         In [9]: ed _\
         Editing... done. Executing edited code...\
         hello world\
         Out[9]: "print 'hello world'\n"
 
         Now we call it with the output #8 (stored in _8, also as Out[8]):
 
         In [10]: ed _8\
         Editing... done. Executing edited code...\
         hello again\
         Out[10]: "print 'hello again'\n"
 
 
         Changing the default editor hook:
 
         If you wish to write your own editor hook, you can put it in a
         configuration file which you load at startup time.  The default hook
         is defined in the IPython.hooks module, and you can use that as a
         starting example for further modifications.  That file also has
         general instructions on how to set a new hook for use once you've
         defined it.
 
 **%env**::
 
 	List environment variables.
 
 **%exit**::
 
 	Exit IPython, confirming if configured to do so.
 
         You can configure whether IPython asks for confirmation upon exit by
         setting the confirm_exit flag in the ipythonrc file.
 
 **%hist**::
 
 	Alternate name for %history.
 
 **%history**::
 
 	Print input history (_i<n> variables), with most recent last.
     
     %history       -> print at most 40 inputs (some may be multi-line)\
     %history n     -> print at most n inputs\
     %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
     
     Each input's number <n> is shown, and is accessible as the
     automatically generated variable _i<n>.  Multi-line statements are
     printed starting at a new line for easy copy/paste.
     
 
     Options:
 
       -n: do NOT print line numbers. This is useful if you want to get a
       printout of many lines which can be directly pasted into a text
       editor.
 
       This feature is only available if numbered prompts are in use.
 
       -t: (default) print the 'translated' history, as IPython understands it.
       IPython filters your input and converts it all into valid Python source
       before executing it (things like magics or aliases are turned into
       function calls, for example). With this option, you'll see the native
       history instead of the user-entered version: '%cd /' will be seen as
       '_ip.magic("%cd /")' instead of '%cd /'.
       
       -r: print the 'raw' history, i.e. the actual commands you typed.
       
       -g: treat the arg as a pattern to grep for in (full) history.
       This includes the "shadow history" (almost all commands ever written).
       Use '%hist -g' to show full shadow history (may be very long).
       In shadow history, every index nuwber starts with 0.
 
       -f FILENAME: instead of printing the output to the screen, redirect it to
        the given file.  The file is always overwritten, though IPython asks for
        confirmation first if it already exists.
 
 **%logoff**::
 
 	Temporarily stop logging.
 
         You must have previously started logging.
 
 **%logon**::
 
 	Restart logging.
 
         This function is for restarting logging which you've temporarily
         stopped with %logoff. For starting logging for the first time, you
         must use the %logstart function, which allows you to specify an
         optional log filename.
 
 **%logstart**::
 
 	Start logging anywhere in a session.
 
         %logstart [-o|-r|-t] [log_name [log_mode]]
 
         If no name is given, it defaults to a file named 'ipython_log.py' in your
         current directory, in 'rotate' mode (see below).
 
         '%logstart name' saves to file 'name' in 'backup' mode.  It saves your
         history up to that point and then continues logging.
 
         %logstart takes a second optional parameter: logging mode. This can be one
         of (note that the modes are given unquoted):\
           append: well, that says it.\
           backup: rename (if exists) to name~ and start name.\
           global: single logfile in your home dir, appended to.\
           over  : overwrite existing log.\
           rotate: create rotating logs name.1~, name.2~, etc.
 
         Options:
 
           -o: log also IPython's output.  In this mode, all commands which
           generate an Out[NN] prompt are recorded to the logfile, right after
           their corresponding input line.  The output lines are always
           prepended with a '#[Out]# ' marker, so that the log remains valid
           Python code.
 
           Since this marker is always the same, filtering only the output from
           a log is very easy, using for example a simple awk call:
 
             awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
 
           -r: log 'raw' input.  Normally, IPython's logs contain the processed
           input, so that user lines are logged in their final form, converted
           into valid Python.  For example, %Exit is logged as
           '_ip.magic("Exit").  If the -r flag is given, all input is logged
           exactly as typed, with no transformations applied.
 
           -t: put timestamps before each input line logged (these are put in
           comments).
 
 **%logstate**::
 
 	Print the status of the logging system.
 
 **%logstop**::
 
 	Fully stop logging and close log file.
 
         In order to start logging again, a new %logstart call needs to be made,
         possibly (though not necessarily) with a new filename, mode and other
         options.
 
 **%lsmagic**::
 
 	List currently available magic functions.
 
 **%macro**::
 
 	Define a set of input lines as a macro for future re-execution.
 
         Usage:\
           %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         This will define a global variable called `name` which is a string
         made of joining the slices and lines you specify (n1,n2,... numbers
         above) from your input history into a single string. This variable
         acts like an automatic function which re-executes those lines as if
         you had typed them. You just type 'name' at the prompt and the code
         executes.
 
         The notation for indicating number ranges is: n1-n2 means 'use line
         numbers n1,...n2' (the endpoint is included).  That is, '5-7' means
         using the lines numbered 5,6 and 7.
 
         Note: as a 'hidden' feature, you can also use traditional python slice
         notation, where N:M means numbers N through M-1.
 
         For example, if your history contains (%hist prints it):
         
           44: x=1\
           45: y=3\
           46: z=x+y\
           47: print x\
           48: a=5\
           49: print 'x',x,'y',y\
 
         you can create a macro with lines 44 through 47 (included) and line 49
         called my_macro with:
 
           In [51]: %macro my_macro 44-47 49
 
         Now, typing `my_macro` (without quotes) will re-execute all this code
         in one pass.
 
         You don't need to give the line-numbers in order, and any given line
         number can appear multiple times. You can assemble macros with any
         lines from your input history in any order.
 
         The macro is a simple object which holds its value in an attribute,
         but IPython's display system checks for macros and executes them as
         code instead of printing them when you type their name.
 
         You can view a macro's contents by explicitly printing it with:
         
           'print macro_name'.
 
         For one-off cases which DON'T contain magic function calls in them you
         can obtain similar results by explicitly executing slices from your
         input history with:
 
           In [60]: exec In[44:48]+In[49]
 
 **%magic**::
 
 	Print information about the magic function system.
 
 **%mglob**::
 
 	    This program allows specifying filenames with "mglob" mechanism.
     Supported syntax in globs (wilcard matching patterns)::
     
      *.cpp ?ellowo*                
          - obvious. Differs from normal glob in that dirs are not included.
            Unix users might want to write this as: "*.cpp" "?ellowo*"
      rec:/usr/share=*.txt,*.doc    
          - get all *.txt and *.doc under /usr/share, 
            recursively
      rec:/usr/share
          - All files under /usr/share, recursively
      rec:*.py
          - All .py files under current working dir, recursively
      foo                           
          - File or dir foo
      !*.bak readme*                   
          - readme*, exclude files ending with .bak
      !.svn/ !.hg/ !*_Data/ rec:.
          - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
            Trailing / is the key, \ does not work!
      dir:foo                       
          - the directory foo if it exists (not files in foo)
      dir:*                         
          - all directories in current folder
      foo.py bar.* !h* rec:*.py
          - Obvious. !h* exclusion only applies for rec:*.py.
            foo.py is *not* included twice.
      @filelist.txt
          - All files listed in 'filelist.txt' file, on separate lines.
 
 **%page**::
 
 	Pretty print the object and display it through a pager.
         
         %page [options] OBJECT
 
         If no object is given, use _ (last output).
         
         Options:
 
           -r: page str(object), don't pretty-print it.
 
 **%pdb**::
 
 	Control the automatic calling of the pdb interactive debugger.
 
         Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
         argument it works as a toggle.
 
         When an exception is triggered, IPython can optionally call the
         interactive pdb debugger after the traceback printout. %pdb toggles
         this feature on and off.
 
         The initial state of this feature is set in your ipythonrc
         configuration file (the variable is called 'pdb').
 
         If you want to just activate the debugger AFTER an exception has fired,
         without having to type '%pdb on' and rerunning your code, you can use
         the %debug magic.
 
 **%pdef**::
 
 	Print the definition header for any callable object.
 
         If the object is a class, print the constructor information.
 
 **%pdoc**::
 
 	Print the docstring for an object.
 
         If the given object is a class, it will print both the class and the
         constructor docstrings.
 
 **%pfile**::
 
 	Print (or run through pager) the file where an object is defined.
 
         The file opens at the line where the object definition begins. IPython
         will honor the environment variable PAGER if set, and otherwise will
         do its best to print the file in a convenient form.
 
         If the given argument is not an object currently defined, IPython will
         try to interpret it as a filename (automatically adding a .py extension
         if needed). You can thus use %pfile as a syntax highlighting code
         viewer.
 
 **%pinfo**::
 
 	Provide detailed information about an object.
     
         '%pinfo object' is just a synonym for object? or ?object.
 
 **%popd**::
 
 	Change to directory popped off the top of the stack.
 
 **%profile**::
 
 	Print your currently active IPyhton profile.
 
 **%prun**::
 
 	Run a statement through the python code profiler.
 
         Usage:\
           %prun [options] statement
 
         The given statement (which doesn't require quote marks) is run via the
         python profiler in a manner similar to the profile.run() function.
         Namespaces are internally managed to work correctly; profile.run
         cannot be used in IPython because it makes certain assumptions about
         namespaces which do not hold under IPython.
 
         Options:
 
         -l <limit>: you can place restrictions on what or how much of the
         profile gets printed. The limit value can be:
 
           * A string: only information for function names containing this string
           is printed.
 
           * An integer: only these many lines are printed.
 
           * A float (between 0 and 1): this fraction of the report is printed
           (for example, use a limit of 0.4 to see the topmost 40% only).
 
         You can combine several limits with repeated use of the option. For
         example, '-l __init__ -l 5' will print only the topmost 5 lines of
         information about class constructors.
 
         -r: return the pstats.Stats object generated by the profiling. This
         object has all the information about the profile in it, and you can
         later use it for further analysis or in other functions.
 
        -s <key>: sort profile by given key. You can provide more than one key
         by using the option several times: '-s key1 -s key2 -s key3...'. The
         default sorting key is 'time'.
 
         The following is copied verbatim from the profile documentation
         referenced below:
 
         When more than one key is provided, additional keys are used as
         secondary criteria when the there is equality in all keys selected
         before them.
         
         Abbreviations can be used for any key names, as long as the
         abbreviation is unambiguous.  The following are the keys currently
         defined:
 
                 Valid Arg       Meaning\
                   "calls"      call count\
                   "cumulative" cumulative time\
                   "file"       file name\
                   "module"     file name\
                   "pcalls"     primitive call count\
                   "line"       line number\
                   "name"       function name\
                   "nfl"        name/file/line\
                   "stdname"    standard name\
                   "time"       internal time
 
         Note that all sorts on statistics are in descending order (placing
         most time consuming items first), where as name, file, and line number
         searches are in ascending order (i.e., alphabetical). The subtle
         distinction between "nfl" and "stdname" is that the standard name is a
         sort of the name as printed, which means that the embedded line
         numbers get compared in an odd way.  For example, lines 3, 20, and 40
         would (if the file names were the same) appear in the string order
         "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
         line numbers.  In fact, sort_stats("nfl") is the same as
         sort_stats("name", "file", "line").
 
         -T <filename>: save profile results as shown on screen to a text
         file. The profile is still shown on screen.
 
         -D <filename>: save (via dump_stats) profile statistics to given
         filename. This data is in a format understod by the pstats module, and
         is generated by a call to the dump_stats() method of profile
         objects. The profile is still shown on screen.
 
         If you want to run complete programs under the profiler's control, use
         '%run -p [prof_opts] filename.py [args to program]' where prof_opts
         contains profiler specific options as described here.
         
         You can read the complete documentation for the profile module with:\
           In [1]: import profile; profile.help()
 
 **%psearch**::
 
 	Search for object in namespaces by wildcard.
 
         %psearch [options] PATTERN [OBJECT TYPE]
 
         Note: ? can be used as a synonym for %psearch, at the beginning or at
         the end: both a*? and ?a* are equivalent to '%psearch a*'.  Still, the
         rest of the command line must be unchanged (options come first), so
         for example the following forms are equivalent
 
         %psearch -i a* function
         -i a* function?
         ?-i a* function
 
         Arguments:
         
           PATTERN
 
           where PATTERN is a string containing * as a wildcard similar to its
           use in a shell.  The pattern is matched in all namespaces on the
           search path. By default objects starting with a single _ are not
           matched, many IPython generated objects have a single
           underscore. The default is case insensitive matching. Matching is
           also done on the attributes of objects and not only on the objects
           in a module.
 
           [OBJECT TYPE]
 
           Is the name of a python type from the types module. The name is
           given in lowercase without the ending type, ex. StringType is
           written string. By adding a type here only objects matching the
           given type are matched. Using all here makes the pattern match all
           types (this is the default).
 
         Options:
 
           -a: makes the pattern match even objects whose names start with a
           single underscore.  These names are normally ommitted from the
           search.
 
           -i/-c: make the pattern case insensitive/sensitive.  If neither of
           these options is given, the default is read from your ipythonrc
           file.  The option name which sets this value is
           'wildcards_case_sensitive'.  If this option is not specified in your
           ipythonrc file, IPython's internal default is to do a case sensitive
           search.
 
           -e/-s NAMESPACE: exclude/search a given namespace.  The pattern you
           specifiy can be searched in any of the following namespaces:
           'builtin', 'user', 'user_global','internal', 'alias', where
           'builtin' and 'user' are the search defaults.  Note that you should
           not use quotes when specifying namespaces.
 
           'Builtin' contains the python module builtin, 'user' contains all
           user data, 'alias' only contain the shell aliases and no python
           objects, 'internal' contains objects used by IPython.  The
           'user_global' namespace is only used by embedded IPython instances,
           and it contains module-level globals.  You can add namespaces to the
           search with -s or exclude them with -e (these options can be given
           more than once).
     
         Examples:
        
         %psearch a*            -> objects beginning with an a
         %psearch -e builtin a* -> objects NOT in the builtin space starting in a
         %psearch a* function   -> all functions beginning with an a
         %psearch re.e*         -> objects beginning with an e in module re
         %psearch r*.e*         -> objects that start with e in modules starting in r
         %psearch r*.* string   -> all strings in modules beginning with r
 
         Case sensitve search:
        
         %psearch -c a*         list all object beginning with lower case a
 
         Show objects beginning with a single _:
        
         %psearch -a _*         list objects beginning with a single underscore
 
 **%psource**::
 
 	Print (or run through pager) the source code for an object.
 
 **%pushd**::
 
 	Place the current dir on stack and change directory.
         
         Usage:\
           %pushd ['dirname']
 
 **%pwd**::
 
 	Return the current working directory path.
 
 **%pycat**::
 
 	Show a syntax-highlighted file through a pager.
 
         This magic is similar to the cat utility, but it will assume the file
         to be Python source and will show it with syntax highlighting.
 
 **%quickref**::
 
 	 Show a quick reference sheet
 
 **%quit**::
 
 	Exit IPython, confirming if configured to do so (like %exit)
 
 **%r**::
 
 	Repeat previous input.
 
         Note: Consider using the more powerfull %rep instead!
         
         If given an argument, repeats the previous command which starts with
         the same string, otherwise it just repeats the previous input.
 
         Shell escaped commands (with ! as first character) are not recognized
         by this system, only pure python code and magic commands.
 
 **%rehashdir**::
 
 	 Add executables in all specified dirs to alias table
      
     Usage:
 
     %rehashdir c:/bin;c:/tools
       - Add all executables under c:/bin and c:/tools to alias table, in 
       order to make them directly executable from any directory.
         
       Without arguments, add all executables in current directory.
 
 **%rehashx**::
 
 	Update the alias table with all executable files in $PATH.
 
         This version explicitly checks that every entry in $PATH is a file
         with execute access (os.X_OK), so it is much slower than %rehash.
 
         Under Windows, it checks executability as a match agains a
         '|'-separated string of extensions, stored in the IPython config
         variable win_exec_ext.  This defaults to 'exe|com|bat'.
         
         This function also resets the root module cache of module completer,
         used on slow filesystems.
 
 **%rep**::
 
 	 Repeat a command, or get command to input line for editing
 
     - %rep (no arguments):
     
     Place a string version of last computation result (stored in the special '_'
     variable) to the next input prompt. Allows you to create elaborate command
     lines without using copy-paste::
     
         $ l = ["hei", "vaan"]       
         $ "".join(l)        
         ==> heivaan        
         $ %rep        
         $ heivaan_ <== cursor blinking    
     
     %rep 45
     
     Place history line 45 to next input prompt. Use %hist to find out the
     number.
     
     %rep 1-4 6-7 3
     
     Repeat the specified lines immediately. Input slice syntax is the same as
     in %macro and %save.
     
     %rep foo
     
     Place the most recent line that has the substring "foo" to next input.
     (e.g. 'svn ci -m foobar').
 
 **%reset**::
 
 	Resets the namespace by removing all names defined by the user.
 
         Input/Output history are left around in case you need them.
 
 **%run**::
 
 	Run the named file inside IPython as a program.
 
         Usage:\
           %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
         
         Parameters after the filename are passed as command-line arguments to
         the program (put in sys.argv). Then, control returns to IPython's
         prompt.
 
         This is similar to running at a system prompt:\
           $ python file args\
         but with the advantage of giving you IPython's tracebacks, and of
         loading all variables into your interactive namespace for further use
         (unless -p is used, see below).
 
         The file is executed in a namespace initially consisting only of
         __name__=='__main__' and sys.argv constructed as indicated. It thus
         sees its environment as if it were being run as a stand-alone program
         (except for sharing global objects such as previously imported
         modules). But after execution, the IPython interactive namespace gets
         updated with all variables defined in the program (except for __name__
         and sys.argv). This allows for very convenient loading of code for
         interactive work, while giving each program a 'clean sheet' to run in.
 
         Options:
         
         -n: __name__ is NOT set to '__main__', but to the running file's name
         without extension (as python does under import).  This allows running
         scripts and reloading the definitions in them without calling code
         protected by an ' if __name__ == "__main__" ' clause.
 
         -i: run the file in IPython's namespace instead of an empty one. This
         is useful if you are experimenting with code written in a text editor
         which depends on variables defined interactively.
 
         -e: ignore sys.exit() calls or SystemExit exceptions in the script
         being run.  This is particularly useful if IPython is being used to
         run unittests, which always exit with a sys.exit() call.  In such
         cases you are interested in the output of the test results, not in
         seeing a traceback of the unittest module.
 
         -t: print timing information at the end of the run.  IPython will give
         you an estimated CPU time consumption for your script, which under
         Unix uses the resource module to avoid the wraparound problems of
         time.clock().  Under Unix, an estimate of time spent on system tasks
         is also given (for Windows platforms this is reported as 0.0).
 
         If -t is given, an additional -N<N> option can be given, where <N>
         must be an integer indicating how many times you want the script to
         run.  The final timing report will include total and per run results.
 
         For example (testing the script uniq_stable.py):
 
             In [1]: run -t uniq_stable
 
             IPython CPU timings (estimated):\
               User  :    0.19597 s.\
               System:        0.0 s.\
 
             In [2]: run -t -N5 uniq_stable
 
             IPython CPU timings (estimated):\
             Total runs performed: 5\
               Times :      Total       Per run\
               User  :   0.910862 s,  0.1821724 s.\
               System:        0.0 s,        0.0 s.
 
         -d: run your program under the control of pdb, the Python debugger.
         This allows you to execute your program step by step, watch variables,
         etc.  Internally, what IPython does is similar to calling:
         
           pdb.run('execfile("YOURFILENAME")')
 
         with a breakpoint set on line 1 of your file.  You can change the line
         number for this automatic breakpoint to be <N> by using the -bN option
         (where N must be an integer).  For example:
 
           %run -d -b40 myscript
 
         will set the first breakpoint at line 40 in myscript.py.  Note that
         the first breakpoint must be set on a line which actually does
         something (not a comment or docstring) for it to stop execution.
 
         When the pdb debugger starts, you will see a (Pdb) prompt.  You must
         first enter 'c' (without qoutes) to start execution up to the first
         breakpoint.
 
         Entering 'help' gives information about the use of the debugger.  You
         can easily see pdb's full documentation with "import pdb;pdb.help()"
         at a prompt.
 
         -p: run program under the control of the Python profiler module (which
         prints a detailed report of execution times, function calls, etc).
 
         You can pass other options after -p which affect the behavior of the
         profiler itself. See the docs for %prun for details.
 
         In this mode, the program's variables do NOT propagate back to the
         IPython interactive namespace (because they remain in the namespace
         where the profiler executes them).
 
         Internally this triggers a call to %prun, see its documentation for
         details on the options available specifically for profiling.
 
         There is one special usage for which the text above doesn't apply:
         if the filename ends with .ipy, the file is run as ipython script,
         just as if the commands were written on IPython prompt.
 
 **%runlog**::
 
 	Run files as logs.
 
         Usage:\
           %runlog file1 file2 ...
 
         Run the named files (treating them as log files) in sequence inside
         the interpreter, and return to the prompt.  This is much slower than
         %run because each line is executed in a try/except block, but it
         allows running files with syntax errors in them.
 
         Normally IPython will guess when a file is one of its own logfiles, so
         you can typically use %run even for logs. This shorthand allows you to
         force any file to be treated as a log file.
 
 **%save**::
 
 	Save a set of lines to a given filename.
 
         Usage:\
           %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         This function uses the same syntax as %macro for line extraction, but
         instead of creating a macro it saves the resulting string to the
         filename you specify.
 
         It adds a '.py' extension to the file if you don't do so yourself, and
         it asks for confirmation before overwriting existing files.
 
 **%sc**::
 
 	Shell capture - execute a shell command and capture its output.
 
         DEPRECATED. Suboptimal, retained for backwards compatibility.
         
         You should use the form 'var = !command' instead. Example:
          
          "%sc -l myfiles = ls ~" should now be written as
             
          "myfiles = !ls ~"
          
         myfiles.s, myfiles.l and myfiles.n still apply as documented
         below.
 
         --
         %sc [options] varname=command
 
         IPython will run the given command using commands.getoutput(), and
         will then update the user's interactive namespace with a variable
         called varname, containing the value of the call.  Your command can
         contain shell wildcards, pipes, etc.
 
         The '=' sign in the syntax is mandatory, and the variable name you
         supply must follow Python's standard conventions for valid names.
         
         (A special format without variable name exists for internal use)
 
         Options:
 
           -l: list output.  Split the output on newlines into a list before
           assigning it to the given variable.  By default the output is stored
           as a single string.
 
           -v: verbose.  Print the contents of the variable.
 
         In most cases you should not need to split as a list, because the
         returned value is a special type of string which can automatically
         provide its contents either as a list (split on newlines) or as a
         space-separated string.  These are convenient, respectively, either
         for sequential processing or to be passed to a shell command.
 
         For example:
 
             # Capture into variable a
             In [9]: sc a=ls *py
 
             # a is a string with embedded newlines
             In [10]: a
             Out[10]: 'setup.py win32_manual_post_install.py'
 
             # which can be seen as a list:
             In [11]: a.l
             Out[11]: ['setup.py', 'win32_manual_post_install.py']
 
             # or as a whitespace-separated string:
             In [12]: a.s
             Out[12]: 'setup.py win32_manual_post_install.py'
 
             # a.s is useful to pass as a single command line:
             In [13]: !wc -l $a.s
               146 setup.py
               130 win32_manual_post_install.py
               276 total
 
             # while the list form is useful to loop over:
             In [14]: for f in a.l:
                ....:      !wc -l $f
                ....:
             146 setup.py
             130 win32_manual_post_install.py
 
         Similiarly, the lists returned by the -l option are also special, in
         the sense that you can equally invoke the .s attribute on them to
         automatically get a whitespace-separated string from their contents:
 
             In [1]: sc -l b=ls *py
 
             In [2]: b
             Out[2]: ['setup.py', 'win32_manual_post_install.py']
 
             In [3]: b.s
             Out[3]: 'setup.py win32_manual_post_install.py'
 
         In summary, both the lists and strings used for ouptut capture have
         the following special attributes:
 
             .l (or .list) : value as list.
             .n (or .nlstr): value as newline-separated string.
             .s (or .spstr): value as space-separated string.
 
 **%store**::
 
 	Lightweight persistence for python variables.
 
     Example:
     
     ville@badger[~]|1> A = ['hello',10,'world']\
     ville@badger[~]|2> %store A\
     ville@badger[~]|3> Exit
     
     (IPython session is closed and started again...)
     
     ville@badger:~$ ipython -p pysh\
     ville@badger[~]|1> print A
     
     ['hello', 10, 'world']
     
     Usage:
     
     %store          - Show list of all variables and their current values\
     %store <var>    - Store the *current* value of the variable to disk\
     %store -d <var> - Remove the variable and its value from storage\
     %store -z       - Remove all variables from storage\
     %store -r       - Refresh all variables from store (delete current vals)\
     %store foo >a.txt  - Store value of foo to new file a.txt\
     %store foo >>a.txt - Append value of foo to file a.txt\   
     
     It should be noted that if you change the value of a variable, you
     need to %store it again if you want to persist the new value.
     
     Note also that the variables will need to be pickleable; most basic
     python types can be safely %stored.
     
     Also aliases can be %store'd across sessions.
 
 **%sx**::
 
 	Shell execute - run a shell command and capture its output.
 
         %sx command
 
         IPython will run the given command using commands.getoutput(), and
         return the result formatted as a list (split on '\n').  Since the
         output is _returned_, it will be stored in ipython's regular output
         cache Out[N] and in the '_N' automatic variables.
 
         Notes:
 
         1) If an input line begins with '!!', then %sx is automatically
         invoked.  That is, while:
           !ls
         causes ipython to simply issue system('ls'), typing
           !!ls
         is a shorthand equivalent to:
           %sx ls
         
         2) %sx differs from %sc in that %sx automatically splits into a list,
         like '%sc -l'.  The reason for this is to make it as easy as possible
         to process line-oriented shell output via further python commands.
         %sc is meant to provide much finer control, but requires more
         typing.
 
         3) Just like %sc -l, this is a list with special attributes:
 
           .l (or .list) : value as list.
           .n (or .nlstr): value as newline-separated string.
           .s (or .spstr): value as whitespace-separated string.
 
         This is very useful when trying to use such lists as arguments to
         system commands.
 
 **%system_verbose**::
 
 	Set verbose printing of system calls.
 
         If called without an argument, act as a toggle
 
 **%time**::
 
 	Time execution of a Python statement or expression.
 
         The CPU and wall clock times are printed, and the value of the
         expression (if any) is returned.  Note that under Win32, system time
         is always reported as 0, since it can not be measured.
 
         This function provides very basic timing functionality.  In Python
         2.3, the timeit module offers more control and sophistication, so this
         could be rewritten to use it (patches welcome).
         
         Some examples:
 
           In [1]: time 2**128
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
           Out[1]: 340282366920938463463374607431768211456L
 
           In [2]: n = 1000000
 
           In [3]: time sum(range(n))
           CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
           Wall time: 1.37
           Out[3]: 499999500000L
 
           In [4]: time print 'hello world'
           hello world
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
 
           Note that the time needed by Python to compile the given expression
           will be reported if it is more than 0.1s.  In this example, the
           actual exponentiation is done by Python at compilation time, so while
           the expression can take a noticeable amount of time to compute, that
           time is purely due to the compilation:
 
           In [5]: time 3**9999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
 
           In [6]: time 3**999999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
           Compiler : 0.78 s
 
 **%timeit**::
 
 	Time execution of a Python statement or expression
 
         Usage:\
           %timeit [-n<N> -r<R> [-t|-c]] statement
 
         Time execution of a Python statement or expression using the timeit
         module.
 
         Options:
         -n<N>: execute the given statement <N> times in a loop. If this value
         is not given, a fitting value is chosen. 
         
         -r<R>: repeat the loop iteration <R> times and take the best result.
         Default: 3
         
         -t: use time.time to measure the time, which is the default on Unix.
         This function measures wall time.
         
         -c: use time.clock to measure the time, which is the default on
         Windows and measures wall time. On Unix, resource.getrusage is used
         instead and returns the CPU user time.
 
         -p<P>: use a precision of <P> digits to display the timing result.
         Default: 3
 
         
         Examples:\
           In [1]: %timeit pass
           10000000 loops, best of 3: 53.3 ns per loop
 
           In [2]: u = None
 
           In [3]: %timeit u is None
           10000000 loops, best of 3: 184 ns per loop
 
           In [4]: %timeit -r 4 u == None
           1000000 loops, best of 4: 242 ns per loop
 
           In [5]: import time
 
           In [6]: %timeit -n1 time.sleep(2)
           1 loops, best of 3: 2 s per loop
           
 
         The times reported by %timeit will be slightly higher than those
         reported by the timeit.py script when variables are accessed. This is
         due to the fact that %timeit executes the statement in the namespace
         of the shell, compared with timeit.py, which uses a single setup
         statement to import function or create variables. Generally, the bias
         does not matter as long as results from timeit.py are not mixed with
         those from %timeit.
 
 **%unalias**::
 
 	Remove an alias
 
 **%upgrade**::
 
 	 Upgrade your IPython installation
         
         This will copy the config files that don't yet exist in your 
         ipython dir from the system config dir. Use this after upgrading 
         IPython if you don't wish to delete your .ipython dir.
 
         Call with -nolegacy to get rid of ipythonrc* files (recommended for
         new users)
 
 **%which**::
 
 	 %which <cmd> => search PATH for files matching cmd. Also scans aliases.
 
     Traverses PATH and prints all files (not just executables!) that match the
     pattern on command line. Probably more useful in finding stuff
     interactively than 'which', which only prints the first matching item.
     
     Also discovers and expands aliases, so you'll see what will be executed
     when you call an alias.
     
     Example:
     
     [~]|62> %which d
     d -> ls -F --color=auto
       == c:\cygwin\bin\ls.exe
     c:\cygwin\bin\d.exe
     
     [~]|64> %which diff*
     diff3 -> diff3
       == c:\cygwin\bin\diff3.exe
     diff -> diff
       == c:\cygwin\bin\diff.exe
     c:\cygwin\bin\diff.exe
     c:\cygwin\bin\diff3.exe
 
 **%who**::
 
 	Print all interactive variables, with some minimal formatting.
 
         If any arguments are given, only variables whose type matches one of
         these are printed.  For example:
 
           %who function str
 
         will only list functions and strings, excluding all other types of
         variables.  To find the proper type names, simply use type(var) at a
         command line to see how python prints type names.  For example:
 
           In [1]: type('hello')\
           Out[1]: <type 'str'>
 
         indicates that the type name for strings is 'str'.
 
         %who always excludes executed names loaded through your configuration
         file and things which are internal to IPython.
 
         This is deliberate, as typically you may load many modules and the
         purpose of %who is to show you only what you've manually defined.
 
 **%who_ls**::
 
 	Return a sorted list of all interactive variables.
 
         If arguments are given, only variables of types matching these
         arguments are returned.
 
 **%whos**::
 
 	Like %who, but gives some extra information about each variable.
 
         The same type filtering of %who can be applied here.
 
         For all variables, the type is printed. Additionally it prints:
         
           - For {},[],(): their length.
 
           - For numpy and Numeric arrays, a summary with shape, number of
           elements, typecode and size in memory.
 
           - Everything else: a string representation, snipping their middle if
           too long.
 
 **%xmode**::
 
 	Switch modes for the exception handlers.
 
         Valid modes: Plain, Context and Verbose.
 
         If called without arguments, acts as a toggle.
 
 .. magic_end
 
 Access to the standard Python help
 ----------------------------------
 
-As of Python 2.1, a help system is available with access to object
-docstrings and the Python manuals. Simply type 'help' (no quotes) to
-access it. You can also type help(object) to obtain information about a
-given object, and help('keyword') for information on a keyword. As noted
-in sec. `accessing help`_, you need to properly configure
-your environment variable PYTHONDOCS for this feature to work correctly.
+As of Python 2.1, a help system is available with access to object docstrings
+and the Python manuals. Simply type 'help' (no quotes) to access it. You can
+also type help(object) to obtain information about a given object, and
+help('keyword') for information on a keyword. As noted :ref:`here
+<accessing_help>`, you need to properly configure your environment variable
+PYTHONDOCS for this feature to work correctly.
 
+.. _dynamic_object_info:
 
 Dynamic object information
 --------------------------
 
 Typing ?word or word? prints detailed information about an object. If
 certain strings in the object are too long (docstrings, code, etc.) they
 get snipped in the center for brevity. This system gives access variable
 types and values, full source code for any object (if available),
 function prototypes and other useful information.
 
 Typing ??word or word?? gives access to the full information without
 snipping long strings. Long strings are sent to the screen through the
 less pager if longer than the screen and printed otherwise. On systems
 lacking the less command, IPython uses a very basic internal pager.
 
 The following magic functions are particularly useful for gathering
 information about your working environment. You can get more details by
 typing %magic or querying them individually (use %function_name? with or
 without the %), this is just a summary:
 
     * **%pdoc <object>**: Print (or run through a pager if too long) the
       docstring for an object. If the given object is a class, it will
       print both the class and the constructor docstrings.
     * **%pdef <object>**: Print the definition header for any callable
       object. If the object is a class, print the constructor information.
     * **%psource <object>**: Print (or run through a pager if too long)
       the source code for an object.
     * **%pfile <object>**: Show the entire source file where an object was
       defined via a pager, opening it at the line where the object
       definition begins.
     * **%who/%whos**: These functions give information about identifiers
       you have defined interactively (not things you loaded or defined
       in your configuration files). %who just prints a list of
       identifiers and %whos prints a table with some basic details about
       each identifier.
 
 Note that the dynamic object information functions (?/??, %pdoc, %pfile,
 %pdef, %psource) give you access to documentation even on things which
 are not really defined as separate identifiers. Try for example typing
 {}.get? or after doing import os, type os.path.abspath??.
 
 
-.. _Readline:
+.. _readline:
 
 Readline-based features
 -----------------------
 
 These features require the GNU readline library, so they won't work if
 your Python installation lacks readline support. We will first describe
 the default behavior IPython uses, and then how to change it to suit
 your preferences.
 
 
 Command line completion
 +++++++++++++++++++++++
 
 At any time, hitting TAB will complete any available python commands or
 variable names, and show you a list of the possible completions if
 there's no unambiguous one. It will also complete filenames in the
 current directory if no python names match what you've typed so far.
 
 
 Search command history
 ++++++++++++++++++++++
 
 IPython provides two ways for searching through previous input and thus
 reduce the need for repetitive typing:
 
    1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
       (next,down) to search through only the history items that match
       what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
       prompt, they just behave like normal arrow keys.
    2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
       searches your history for lines that contain what you've typed so
       far, completing as much as it can.
 
 
 Persistent command history across sessions
 ++++++++++++++++++++++++++++++++++++++++++
 
 IPython will save your input history when it leaves and reload it next
 time you restart it. By default, the history file is named
 $IPYTHONDIR/history, but if you've loaded a named profile,
 '-PROFILE_NAME' is appended to the name. This allows you to keep
 separate histories related to various tasks: commands related to
 numerical work will not be clobbered by a system shell history, for
 example.
 
 
 Autoindent
 ++++++++++
 
 IPython can recognize lines ending in ':' and indent the next line,
 while also un-indenting automatically after 'raise' or 'return'.
 
 This feature uses the readline library, so it will honor your ~/.inputrc
 configuration (or whatever file your INPUTRC variable points to). Adding
 the following lines to your .inputrc file can make indenting/unindenting
 more convenient (M-i indents, M-u unindents)::
 
     $if Python 
     "\M-i": "    "  
     "\M-u": "\d\d\d\d"  
     $endif
 
 Note that there are 4 spaces between the quote marks after "M-i" above.
 
 Warning: this feature is ON by default, but it can cause problems with
 the pasting of multi-line indented code (the pasted code gets
 re-indented on each line). A magic function %autoindent allows you to
 toggle it on/off at runtime. You can also disable it permanently on in
 your ipythonrc file (set autoindent 0).
 
 
 Customizing readline behavior
 +++++++++++++++++++++++++++++
 
 All these features are based on the GNU readline library, which has an
 extremely customizable interface. Normally, readline is configured via a
 file which defines the behavior of the library; the details of the
 syntax for this can be found in the readline documentation available
 with your system or on the Internet. IPython doesn't read this file (if
 it exists) directly, but it does support passing to readline valid
 options via a simple interface. In brief, you can customize readline by
 setting the following options in your ipythonrc configuration file (note
 that these options can not be specified at the command line):
 
     * **readline_parse_and_bind**: this option can appear as many times as
       you want, each time defining a string to be executed via a
       readline.parse_and_bind() command. The syntax for valid commands
       of this kind can be found by reading the documentation for the GNU
       readline library, as these commands are of the kind which readline
       accepts in its configuration file.
     * **readline_remove_delims**: a string of characters to be removed
       from the default word-delimiters list used by readline, so that
       completions may be performed on strings which contain them. Do not
       change the default value unless you know what you're doing.
     * **readline_omit__names**: when tab-completion is enabled, hitting
       <tab> after a '.' in a name will complete all attributes of an
       object, including all the special methods whose names include
       double underscores (like __getitem__ or __class__). If you'd
       rather not see these names by default, you can set this option to
       1. Note that even when this option is set, you can still see those
       names by explicitly typing a _ after the period and hitting <tab>:
       'name._<tab>' will always complete attribute names starting with '_'.
       
       This option is off by default so that new users see all
       attributes of any objects they are dealing with.
 
 You will find the default values along with a corresponding detailed
 explanation in your ipythonrc file.
 
 
 Session logging and restoring
 -----------------------------
 
-You can log all input from a session either by starting IPython with
-the command line switches -log or -logfile (see sec. `command line
-options`_) or by activating the logging at any moment with the magic
-function %logstart.
+You can log all input from a session either by starting IPython with the
+command line switches -log or -logfile (see :ref:`here <command_line_options>`)
+or by activating the logging at any moment with the magic function %logstart.
 
 Log files can later be reloaded with the -logplay option and IPython
 will attempt to 'replay' the log by executing all the lines in it, thus
 restoring the state of a previous session. This feature is not quite
 perfect, but can still be useful in many cases.
 
 The log files can also be used as a way to have a permanent record of
 any code you wrote while experimenting. Log files are regular text files
 which you can later open in your favorite text editor to extract code or
 to 'clean them up' before using them to replay a session.
 
 The %logstart function for activating logging in mid-session is used as
 follows:
 
 %logstart [log_name [log_mode]]
 
 If no name is given, it defaults to a file named 'log' in your
 IPYTHONDIR directory, in 'rotate' mode (see below).
 
 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
 history up to that point and then continues logging.
 
 %logstart takes a second optional parameter: logging mode. This can be
 one of (note that the modes are given unquoted):
 
     * [over:] overwrite existing log_name.
     * [backup:] rename (if exists) to log_name~ and start log_name.
     * [append:] well, that says it.
     * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
 
 The %logoff and %logon functions allow you to temporarily stop and
 resume logging to a file which had previously been started with
 %logstart. They will fail (with an explanation) if you try to use them
 before logging has been started.
 
+.. _system_shell_access:
+
 System shell access
 -------------------
 
 Any input line beginning with a ! character is passed verbatim (minus
 the !, of course) to the underlying operating system. For example,
 typing !ls will run 'ls' in the current directory.
 
 Manual capture of command output
 --------------------------------
 
 If the input line begins with two exclamation marks, !!, the command is
 executed but its output is captured and returned as a python list, split
 on newlines. Any output sent by the subprocess to standard error is
 printed separately, so that the resulting list only captures standard
 output. The !! syntax is a shorthand for the %sx magic command.
 
 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
 but allowing more fine-grained control of the capture details, and
 storing the result directly into a named variable. The direct use of 
 %sc is now deprecated, and you should ise the ``var = !cmd`` syntax
 instead.
 
 IPython also allows you to expand the value of python variables when
 making system calls. Any python variable or expression which you prepend
 with $ will get expanded before the system call is made::
 
     In [1]: pyvar='Hello world' 
     In [2]: !echo "A python variable: $pyvar"  
     A python variable: Hello world
 
 If you want the shell to actually see a literal $, you need to type it
 twice::
 
     In [3]: !echo "A system variable: $$HOME"  
     A system variable: /home/fperez
 
 You can pass arbitrary expressions, though you'll need to delimit them
 with {} if there is ambiguity as to the extent of the expression::
 
     In [5]: x=10 
     In [6]: y=20 
     In [13]: !echo $x+y  
     10+y  
     In [7]: !echo ${x+y}  
     30
 
 Even object attributes can be expanded::
 
     In [12]: !echo $sys.argv  
     [/home/fperez/usr/bin/ipython]
 
 
 System command aliases
 ----------------------
 
 The %alias magic function and the alias option in the ipythonrc
 configuration file allow you to define magic functions which are in fact
 system shell commands. These aliases can have parameters.
 
 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
 Then, typing '%alias_name params' will execute the system command 'cmd
 params' (from your underlying operating system).
 
 You can also define aliases with parameters using %s specifiers (one per
 parameter). The following example defines the %parts function as an
 alias to the command 'echo first %s second %s' where each %s will be
 replaced by a positional parameter to the call to %parts::
 
     In [1]: alias parts echo first %s second %s 
     In [2]: %parts A B 
     first A second B  
     In [3]: %parts A  
     Incorrect number of arguments: 2 expected.  
     parts is an alias to: 'echo first %s second %s'
 
 If called with no parameters, %alias prints the table of currently
 defined aliases.
 
 The %rehash/rehashx magics allow you to load your entire $PATH as
 ipython aliases. See their respective docstrings (or sec. 6.2
 <#sec:magic> for further details).
 
 
 .. _dreload:
 
 Recursive reload
 ----------------
 
 The dreload function does a recursive reload of a module: changes made
 to the module since you imported will actually be available without
 having to exit.
 
 
 Verbose and colored exception traceback printouts
 -------------------------------------------------
 
 IPython provides the option to see very detailed exception tracebacks,
 which can be especially useful when debugging large programs. You can
 run any Python file with the %run function to benefit from these
 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
 be colored (if your terminal supports it) which makes them much easier
 to parse visually.
 
 See the magic xmode and colors functions for details (just type %magic).
 
 These features are basically a terminal version of Ka-Ping Yee's cgitb
 module, now part of the standard Python library.
 
 
-.. _Input caching:
+.. _input_caching:
 
 Input caching system
 --------------------
 
-IPython offers numbered prompts (In/Out) with input and output caching.
-All input is saved and can be retrieved as variables (besides the usual
-arrow key recall).
+IPython offers numbered prompts (In/Out) with input and output caching
+(also referred to as 'input history'). All input is saved and can be 
+retrieved as variables (besides the usual arrow key recall), in 
+addition to the %rep magic command that brings a history entry
+up for editing on the next  command line.
 
 The following GLOBAL variables always exist (so don't overwrite them!):
 _i: stores previous input. _ii: next previous. _iii: next-next previous.
 _ih : a list of all input _ih[n] is the input from line n and this list
 is aliased to the global variable In. If you overwrite In with a
 variable of your own, you can remake the assignment to the internal list
 with a simple 'In=_ih'.
 
 Additionally, global variables named _i<n> are dynamically created (<n>
 being the prompt counter), such that
 _i<n> == _ih[<n>] == In[<n>].
 
 For example, what you typed at prompt 14 is available as _i14, _ih[14]
 and In[14].
 
 This allows you to easily cut and paste multi line interactive prompts
 by printing them out: they print like a clean string, without prompt
 characters. You can also manipulate them like regular variables (they
 are strings), modify or exec them (typing 'exec _i9' will re-execute the
 contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
 9 through 13 and line 18).
 
 You can also re-execute multiple lines of input easily by using the
 magic %macro function (which automates the process and allows
 re-execution without having to type 'exec' every time). The macro system
 also allows you to re-execute previous lines which include magic
 function calls (which require special processing). Type %macro? or see
 sec. 6.2 <#sec:magic> for more details on the macro system.
 
 A history function %hist allows you to see any part of your input
 history by printing a range of the _i variables.
 
-.. _Output caching:
+You can also search ('grep') through your history by typing 
+'%hist -g somestring'. This also searches through the so called *shadow history*,
+which remembers all the commands (apart from multiline code blocks)
+you have ever entered. Handy for searching for svn/bzr URL's, IP adrresses
+etc. You can bring shadow history entries listed by '%hist -g' up for editing 
+(or re-execution by just pressing ENTER) with %rep command. Shadow history 
+entries are not available as _iNUMBER variables, and they are identified by 
+the '0' prefix in %hist -g output. That is, history entry 12 is a normal 
+history entry, but 0231 is a shadow history entry.
+
+Shadow history was added because the readline history is inherently very
+unsafe - if you have multiple IPython sessions open, the last session 
+to close will overwrite the history of previountly closed session. Likewise,
+if a crash occurs, history is never saved, whereas shadow history entries
+are added after entering every command (so a command executed 
+in another IPython session is immediately available in other IPython 
+sessions that are open).
+
+To conserve space, a command can exist in shadow history only once - it doesn't 
+make sense to store a common line like "cd .." a thousand times. The idea is 
+mainly to provide a reliable place where valuable, hard-to-remember commands can 
+always be retrieved, as opposed to providing an exact sequence of commands
+you have entered in actual order.
+
+Because shadow history has all the commands you have ever executed,
+time taken by %hist -g will increase oven time. If it ever starts to take
+too long (or it ends up containing sensitive information like passwords), 
+clear the shadow history by `%clear shadow_nuke`.
+
+Time taken to add entries to shadow history should be negligible, but 
+in any case, if you start noticing performance degradation after using 
+IPython for a long time (or running a script that floods the shadow history!), 
+you can 'compress' the shadow history by executing 
+`%clear shadow_compress`. In practice, this should never be necessary
+in normal use.
+
+.. _output_caching:
 
 Output caching system
 ---------------------
 
 For output that is returned from actions, a system similar to the input
 cache exists but using _ instead of _i. Only actions that produce a
 result (NOT assignments, for example) are cached. If you are familiar
 with Mathematica, IPython's _ variables behave exactly like
 Mathematica's % variables.
 
 The following GLOBAL variables always exist (so don't overwrite them!):
 
     * [_] (a single underscore) : stores previous output, like Python's
       default interpreter.
     * [__] (two underscores): next previous.
     * [___] (three underscores): next-next previous.
 
 Additionally, global variables named _<n> are dynamically created (<n>
 being the prompt counter), such that the result of output <n> is always
 available as _<n> (don't use the angle brackets, just the number, e.g.
 _21).
 
 These global variables are all stored in a global dictionary (not a
 list, since it only has entries for lines which returned a result)
 available under the names _oh and Out (similar to _ih and In). So the
 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
 accidentally overwrite the Out variable you can recover it by typing
 'Out=_oh' at the prompt.
 
 This system obviously can potentially put heavy memory demands on your
 system, since it prevents Python's garbage collector from removing any
 previously computed results. You can control how many results are kept
 in memory with the option (at the command line or in your ipythonrc
 file) cache_size. If you set it to 0, the whole system is completely
 disabled and the prompts revert to the classic '>>>' of normal Python.
 
 
 Directory history
 -----------------
 
 Your history of visited directories is kept in the global list _dh, and
 the magic %cd command can be used to go to any entry in that list. The
-%dhist command allows you to view this history. do ``cd -<TAB`` to
+%dhist command allows you to view this history. Do ``cd -<TAB`` to
 conventiently view the directory history.
 
 
 Automatic parentheses and quotes
 --------------------------------
 
 These features were adapted from Nathan Gray's LazyPython. They are
 meant to allow less typing for common situations.
 
 
 Automatic parentheses
 ---------------------
 
 Callable objects (i.e. functions, methods, etc) can be invoked like this
 (notice the commas between the arguments)::
 
     >>> callable_ob arg1, arg2, arg3
 
 and the input will be translated to this::
 
     -> callable_ob(arg1, arg2, arg3)
 
 You can force automatic parentheses by using '/' as the first character
 of a line. For example::
 
     >>> /globals # becomes 'globals()'
 
 Note that the '/' MUST be the first character on the line! This won't work::
 
     >>> print /globals # syntax error
 
 In most cases the automatic algorithm should work, so you should rarely
 need to explicitly invoke /. One notable exception is if you are trying
 to call a function with a list of tuples as arguments (the parenthesis
 will confuse IPython)::
 
     In [1]: zip (1,2,3),(4,5,6) # won't work
 
 but this will work::
 
     In [2]: /zip (1,2,3),(4,5,6) 
     ---> zip ((1,2,3),(4,5,6))  
     Out[2]= [(1, 4), (2, 5), (3, 6)]
 
 IPython tells you that it has altered your command line by displaying
 the new command line preceded by ->. e.g.::
 
     In [18]: callable list 
     ----> callable (list)
 
 
 Automatic quoting
 -----------------
 
 You can force automatic quoting of a function's arguments by using ','
 or ';' as the first character of a line. For example::
 
     >>> ,my_function /home/me # becomes my_function("/home/me")
 
 If you use ';' instead, the whole argument is quoted as a single string
 (while ',' splits on whitespace)::
 
     >>> ,my_function a b c # becomes my_function("a","b","c")
 
     >>> ;my_function a b c # becomes my_function("a b c")
 
 Note that the ',' or ';' MUST be the first character on the line! This
 won't work::
 
     >>> x = ,my_function /home/me # syntax error
 
 IPython as your default Python environment
 ==========================================
 
 Python honors the environment variable PYTHONSTARTUP and will execute at
 startup the file referenced by this variable. If you put at the end of
 this file the following two lines of code::
 
     import IPython 
     IPython.Shell.IPShell().mainloop(sys_exit=1)
 
 then IPython will be your working environment anytime you start Python.
 The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
 it finishes, otherwise you'll be back at the normal Python '>>>'
 prompt.
 
 This is probably useful to developers who manage multiple Python
 versions and don't want to have correspondingly multiple IPython
 versions. Note that in this mode, there is no way to pass IPython any
 command-line options, as those are trapped first by Python itself.
 
 .. _Embedding:
 
 Embedding IPython
 =================
 
 It is possible to start an IPython instance inside your own Python
 programs. This allows you to evaluate dynamically the state of your
 code, operate with your variables, analyze them, etc. Note however that
 any changes you make to values while in the shell do not propagate back
 to the running code, so it is safe to modify your values because you
 won't break your code in bizarre ways by doing so.
 
 This feature allows you to easily have a fully functional python
 environment for doing object introspection anywhere in your code with a
 simple function call. In some cases a simple print statement is enough,
 but if you need to do more detailed analysis of a code fragment this
 feature can be very valuable.
 
 It can also be useful in scientific computing situations where it is
 common to need to do some automatic, computationally intensive part and
 then stop to look at data, plots, etc.
 Opening an IPython instance will give you full access to your data and
 functions, and you can resume program execution once you are done with
 the interactive part (perhaps to stop again later, as many times as
 needed).
 
 The following code snippet is the bare minimum you need to include in
 your Python programs for this to work (detailed examples follow later)::
 
     from IPython.Shell import IPShellEmbed
 
     ipshell = IPShellEmbed()
 
     ipshell() # this call anywhere in your program will start IPython
 
 You can run embedded instances even in code which is itself being run at
 the IPython interactive prompt with '%run <filename>'. Since it's easy
 to get lost as to where you are (in your top-level IPython or in your
 embedded one), it's a good idea in such cases to set the in/out prompts
 to something different for the embedded instances. The code examples
 below illustrate this.
 
 You can also have multiple IPython instances in your program and open
 them separately, for example with different options for data
 presentation. If you close and open the same instance multiple times,
 its prompt counters simply continue from each execution to the next.
 
 Please look at the docstrings in the Shell.py module for more details on
 the use of this system.
 
 The following sample file illustrating how to use the embedding
 functionality is provided in the examples directory as example-embed.py.
 It should be fairly self-explanatory::
 
 
     #!/usr/bin/env python
 
     """An example of how to embed an IPython shell into a running program.
 
     Please see the documentation in the IPython.Shell module for more details.
 
     The accompanying file example-embed-short.py has quick code fragments for
     embedding which you can cut and paste in your code once you understand how
     things work.
 
     The code in this file is deliberately extra-verbose, meant for learning."""
 
     # The basics to get you going:
 
     # IPython sets the __IPYTHON__ variable so you can know if you have nested
     # copies running.
 
     # Try running this code both at the command line and from inside IPython (with
     # %run example-embed.py)
     try:
         __IPYTHON__
     except NameError:
         nested = 0
         args = ['']
     else:
         print "Running nested copies of IPython."
         print "The prompts for the nested copy have been modified"
         nested = 1
         # what the embedded instance will see as sys.argv:
         args = ['-pi1','In <\\#>: ','-pi2','   .\\D.: ',
                 '-po','Out<\\#>: ','-nosep']
 
     # First import the embeddable shell class
     from IPython.Shell import IPShellEmbed
 
     # Now create an instance of the embeddable shell. The first argument is a
     # string with options exactly as you would type them if you were starting
     # IPython at the system command line. Any parameters you want to define for
     # configuration can thus be specified here.
     ipshell = IPShellEmbed(args,
                            banner = 'Dropping into IPython',
                            exit_msg = 'Leaving Interpreter, back to program.')
 
     # Make a second instance, you can have as many as you want.
     if nested:
         args[1] = 'In2<\\#>'
     else:
         args = ['-pi1','In2<\\#>: ','-pi2','   .\\D.: ',
                 '-po','Out<\\#>: ','-nosep']
     ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
 
     print '\nHello. This is printed from the main controller program.\n'
 
     # You can then call ipshell() anywhere you need it (with an optional
     # message):
     ipshell('***Called from top level. '
             'Hit Ctrl-D to exit interpreter and continue program.\n'
             'Note that if you use %kill_embedded, you can fully deactivate\n'
             'This embedded instance so it will never turn on again')
 
     print '\nBack in caller program, moving along...\n'
 
     #---------------------------------------------------------------------------
     # More details:
 
     # IPShellEmbed instances don't print the standard system banner and
     # messages. The IPython banner (which actually may contain initialization
     # messages) is available as <instance>.IP.BANNER in case you want it.
 
     # IPShellEmbed instances print the following information everytime they
     # start:
 
     # - A global startup banner.
 
     # - A call-specific header string, which you can use to indicate where in the
     # execution flow the shell is starting.
 
     # They also print an exit message every time they exit.
 
     # Both the startup banner and the exit message default to None, and can be set
     # either at the instance constructor or at any other time with the
     # set_banner() and set_exit_msg() methods.
 
     # The shell instance can be also put in 'dummy' mode globally or on a per-call
     # basis. This gives you fine control for debugging without having to change
     # code all over the place.
 
     # The code below illustrates all this.
 
 
     # This is how the global banner and exit_msg can be reset at any point
     ipshell.set_banner('Entering interpreter - New Banner')
     ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
 
     def foo(m):
         s = 'spam'
         ipshell('***In foo(). Try @whos, or print s or m:')
         print 'foo says m = ',m
 
     def bar(n):
         s = 'eggs'
         ipshell('***In bar(). Try @whos, or print s or n:')
         print 'bar says n = ',n
 
     # Some calls to the above functions which will trigger IPython:
     print 'Main program calling foo("eggs")\n'
     foo('eggs')
 
     # The shell can be put in 'dummy' mode where calls to it silently return. This
     # allows you, for example, to globally turn off debugging for a program with a
     # single call.
     ipshell.set_dummy_mode(1)
     print '\nTrying to call IPython which is now "dummy":'
     ipshell()
     print 'Nothing happened...'
     # The global 'dummy' mode can still be overridden for a single call
     print '\nOverriding dummy mode manually:'
     ipshell(dummy=0)
 
     # Reactivate the IPython shell
     ipshell.set_dummy_mode(0)
 
     print 'You can even have multiple embedded instances:'
     ipshell2()
 
     print '\nMain program calling bar("spam")\n'
     bar('spam')
 
     print 'Main program finished. Bye!'
 
     #********************** End of file <example-embed.py> ***********************
 
 Once you understand how the system functions, you can use the following
 code fragments in your programs which are ready for cut and paste::
 
 
     """Quick code snippets for embedding IPython into other programs.
 
     See example-embed.py for full details, this file has the bare minimum code for
     cut and paste use once you understand how to use the system."""
 
     #---------------------------------------------------------------------------
     # This code loads IPython but modifies a few things if it detects it's running
     # embedded in another IPython session (helps avoid confusion)
 
     try:
         __IPYTHON__
     except NameError:
         argv = ['']
         banner = exit_msg = ''
     else:
         # Command-line options for IPython (a list like sys.argv)
         argv = ['-pi1','In <\\#>:','-pi2','   .\\D.:','-po','Out<\\#>:']
         banner = '*** Nested interpreter ***'
         exit_msg = '*** Back in main IPython ***'
 
     # First import the embeddable shell class
     from IPython.Shell import IPShellEmbed
     # Now create the IPython shell instance. Put ipshell() anywhere in your code
     # where you want it to open.
     ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
 
     #---------------------------------------------------------------------------
     # This code will load an embeddable IPython shell always with no changes for
     # nested embededings.
 
     from IPython.Shell import IPShellEmbed
     ipshell = IPShellEmbed()
     # Now ipshell() will open IPython anywhere in the code.
 
     #---------------------------------------------------------------------------
     # This code loads an embeddable shell only if NOT running inside
     # IPython. Inside IPython, the embeddable shell variable ipshell is just a
     # dummy function.
 
     try:
         __IPYTHON__
     except NameError:
         from IPython.Shell import IPShellEmbed
         ipshell = IPShellEmbed()
         # Now ipshell() will open IPython anywhere in the code
     else:
         # Define a dummy ipshell() so the same code doesn't crash inside an
         # interactive IPython
         def ipshell(): pass
 
     #******************* End of file <example-embed-short.py> ********************
 
 Using the Python debugger (pdb)
 ===============================
 
 Running entire programs via pdb
 -------------------------------
 
 pdb, the Python debugger, is a powerful interactive debugger which
 allows you to step through code, set breakpoints, watch variables,
 etc.  IPython makes it very easy to start any script under the control
 of pdb, regardless of whether you have wrapped it into a 'main()'
 function or not. For this, simply type '%run -d myscript' at an
 IPython prompt. See the %run command's documentation (via '%run?' or
 in Sec. magic_ for more details, including how to control where pdb
 will stop execution first.
 
 For more information on the use of the pdb debugger, read the included
 pdb.doc file (part of the standard Python distribution). On a stock
 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
 easiest way to read it is by using the help() function of the pdb module
 as follows (in an IPython prompt):
 
 In [1]: import pdb 
 In [2]: pdb.help()
 
 This will load the pdb.doc document in a file viewer for you automatically.
 
 
 Automatic invocation of pdb on exceptions
 -----------------------------------------
 
 IPython, if started with the -pdb option (or if the option is set in
 your rc file) can call the Python pdb debugger every time your code
 triggers an uncaught exception. This feature
 can also be toggled at any time with the %pdb magic command. This can be
 extremely useful in order to find the origin of subtle bugs, because pdb
 opens up at the point in your code which triggered the exception, and
 while your program is at this point 'dead', all the data is still
 available and you can walk up and down the stack frame and understand
 the origin of the problem.
 
 Furthermore, you can use these debugging facilities both with the
 embedded IPython mode and without IPython at all. For an embedded shell
 (see sec. Embedding_), simply call the constructor with
 '-pdb' in the argument string and automatically pdb will be called if an
 uncaught exception is triggered by your code.
 
 For stand-alone use of the feature in your programs which do not use
 IPython at all, put the following lines toward the top of your 'main'
 routine::
 
     import sys,IPython.ultraTB  
     sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
     color_scheme='Linux', call_pdb=1)
 
 The mode keyword can be either 'Verbose' or 'Plain', giving either very
 detailed or normal tracebacks respectively. The color_scheme keyword can
 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
 options which can be set in IPython with -colors and -xmode.
 
 This will give any of your programs detailed, colored tracebacks with
 automatic invocation of pdb.
 
 
 Extensions for syntax processing
 ================================
 
 This isn't for the faint of heart, because the potential for breaking
 things is quite high. But it can be a very powerful and useful feature.
 In a nutshell, you can redefine the way IPython processes the user input
 line to accept new, special extensions to the syntax without needing to
 change any of IPython's own code.
 
 In the IPython/Extensions directory you will find some examples
 supplied, which we will briefly describe now. These can be used 'as is'
 (and both provide very useful functionality), or you can use them as a
 starting point for writing your own extensions.
 
 
 Pasting of code starting with '>>> ' or '... '
 ----------------------------------------------
 
 In the python tutorial it is common to find code examples which have
 been taken from real python sessions. The problem with those is that all
 the lines begin with either '>>> ' or '... ', which makes it impossible
 to paste them all at once. One must instead do a line by line manual
 copying, carefully removing the leading extraneous characters.
 
 This extension identifies those starting characters and removes them
 from the input automatically, so that one can paste multi-line examples
 directly into IPython, saving a lot of time. Please look at the file
 InterpreterPasteInput.py in the IPython/Extensions directory for details
 on how this is done.
 
 IPython comes with a special profile enabling this feature, called
 tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
 will be available. In a normal IPython session you can activate the
 feature by importing the corresponding module with:
 In [1]: import IPython.Extensions.InterpreterPasteInput
 
 The following is a 'screenshot' of how things work when this extension
 is on, copying an example from the standard tutorial::
 
     IPython profile: tutorial 
 
     *** Pasting of code with ">>>" or "..." has been enabled. 
 
     In [1]: >>> def fib2(n): # return Fibonacci series up to n 
        ...: ...     """Return a list containing the Fibonacci series up to
     n.""" 
        ...: ...     result = [] 
        ...: ...     a, b = 0, 1 
        ...: ...     while b < n: 
        ...: ...         result.append(b)    # see below 
        ...: ...         a, b = b, a+b 
        ...: ...     return result 
        ...: 
 
     In [2]: fib2(10) 
     Out[2]: [1, 1, 2, 3, 5, 8]
 
 Note that as currently written, this extension does not recognize
 IPython's prompts for pasting. Those are more complicated, since the
 user can change them very easily, they involve numbers and can vary in
 length. One could however extract all the relevant information from the
 IPython instance and build an appropriate regular expression. This is
 left as an exercise for the reader.
 
 
 Input of physical quantities with units
 ---------------------------------------
 
 The module PhysicalQInput allows a simplified form of input for physical
 quantities with units. This file is meant to be used in conjunction with
 the PhysicalQInteractive module (in the same directory) and
 Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
 (http://dirac.cnrs-orleans.fr/ScientificPython/).
 
 The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
 but these must be declared as instances of a class. For example, to
 define v as a velocity of 3 m/s, normally you would write::
 
     In [1]: v = PhysicalQuantity(3,'m/s')
 
 Using the PhysicalQ_Input extension this can be input instead as: 
 In [1]: v = 3 m/s
 which is much more convenient for interactive use (even though it is
 blatantly invalid Python syntax).
 
 The physics profile supplied with IPython (enabled via 'ipython -p
 physics') uses these extensions, which you can also activate with:
 
 from math import * # math MUST be imported BEFORE PhysicalQInteractive 
 from IPython.Extensions.PhysicalQInteractive import * 
 import IPython.Extensions.PhysicalQInput
 
 
 Threading support
 =================
 
 WARNING: The threading support is still somewhat experimental, and it
 has only seen reasonable testing under Linux. Threaded code is
 particularly tricky to debug, and it tends to show extremely
 platform-dependent behavior. Since I only have access to Linux machines,
 I will have to rely on user's experiences and assistance for this area
 of IPython to improve under other platforms.
 
 IPython, via the -gthread , -qthread, -q4thread and -wthread options
 (described in Sec. `Threading options`_), can run in
 multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications
 respectively. These GUI toolkits need to control the python main loop of
 execution, so under a normal Python interpreter, starting a pyGTK, Qt3,
 Qt4 or WXPython application will immediately freeze the shell.
 
 IPython, with one of these options (you can only use one at a time),
 separates the graphical loop and IPython's code execution run into
 different threads. This allows you to test interactively (with %run, for
 example) your GUI code without blocking.
 
 A nice mini-tutorial on using IPython along with the Qt Designer
 application is available at the SciPy wiki:
 http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
 
 
 Tk issues
 ---------
 
 As indicated in Sec. `Threading options`_, a special -tk option is
 provided to try and allow Tk graphical applications to coexist
 interactively with WX, Qt or GTK ones. Whether this works at all,
 however, is very platform and configuration dependent. Please
 experiment with simple test cases before committing to using this
 combination of Tk and GTK/Qt/WX threading in a production environment.
 
 
 I/O pitfalls
 ------------
 
 Be mindful that the Python interpreter switches between threads every
 $N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
 value can be read by using the sys.getcheckinterval() function, and it
 can be reset via sys.setcheckinterval(N). This switching of threads can
 cause subtly confusing effects if one of your threads is doing file I/O.
 In text mode, most systems only flush file buffers when they encounter a
 '\n'. An instruction as simple as:: 
 
   print >> filehandle, ''hello world''
 
 actually consists of several bytecodes, so it is possible that the
 newline does not reach your file before the next thread switch.
 Similarly, if you are writing to a file in binary mode, the file won't
 be flushed until the buffer fills, and your other thread may see
 apparently truncated files.
 
 For this reason, if you are using IPython's thread support and have (for
 example) a GUI application which will read data generated by files
 written to from the IPython thread, the safest approach is to open all
 of your files in unbuffered mode (the third argument to the file/open
 function is the buffering value)::
 
   filehandle = open(filename,mode,0)
 
 This is obviously a brute force way of avoiding race conditions with the
 file buffering. If you want to do it cleanly, and you have a resource
 which is being shared by the interactive IPython loop and your GUI
 thread, you should really handle it with thread locking and
 syncrhonization properties. The Python documentation discusses these.
 
-.. _Interactive demos:
+.. _interactive_demos:
 
 Interactive demos with IPython
 ==============================
 
 IPython ships with a basic system for running scripts interactively in
 sections, useful when presenting code to audiences. A few tags embedded
 in comments (so that the script remains valid Python code) divide a file
 into separate blocks, and the demo can be run one block at a time, with
 IPython printing (with syntax highlighting) the block before executing
 it, and returning to the interactive prompt after each block. The
 interactive namespace is updated after each block is run with the
 contents of the demo's namespace.
 
 This allows you to show a piece of code, run it and then execute
 interactively commands based on the variables just created. Once you
 want to continue, you simply execute the next block of the demo. The
 following listing shows the markup necessary for dividing a script into
 sections for execution as a demo::
 
 
     """A simple interactive demo to illustrate the use of IPython's Demo class.
 
     Any python script can be run as a demo, but that does little more than showing
     it on-screen, syntax-highlighted in one shot.  If you add a little simple
     markup, you can stop at specified intervals and return to the ipython prompt,
     resuming execution later.
     """
 
     print 'Hello, welcome to an interactive IPython demo.'
     print 'Executing this block should require confirmation before proceeding,'
     print 'unless auto_all has been set to true in the demo object'
 
     # The mark below defines a block boundary, which is a point where IPython will
     # stop execution and return to the interactive prompt.
     # Note that in actual interactive execution, 
     # <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!'
 
 In order to run a file as a demo, you must first make a Demo object out
 of it. If the file is named myscript.py, the following code will make a
 demo::
 
     from IPython.demo import Demo
 
     mydemo = Demo('myscript.py')
 
 This creates the mydemo object, whose blocks you run one at a time by
 simply calling the object with no arguments. If you have autocall active
 in IPython (the default), all you need to do is type::
 
     mydemo 
 
 and IPython will call it, executing each block. Demo objects can be
 restarted, you can move forward or back skipping blocks, re-execute the
 last block, etc. Simply use the Tab key on a demo object to see its
 methods, and call '?' on them to see their docstrings for more usage
 details. In addition, the demo module itself contains a comprehensive
 docstring, which you can access via::
 
     from IPython import demo
 
     demo?
 
 Limitations: It is important to note that these demos are limited to
 fairly simple uses. In particular, you can not put division marks in
 indented code (loops, if statements, function definitions, etc.)
 Supporting something like this would basically require tracking the
 internal execution state of the Python interpreter, so only top-level
 divisions are allowed. If you want to be able to open an IPython
 instance at an arbitrary point in a program, you can use IPython's
 embedding facilities, described in detail in Sec. 9
 
 
 .. _Matplotlib support:
 
 Plotting with matplotlib
 ========================
 
 The matplotlib library (http://matplotlib.sourceforge.net
 http://matplotlib.sourceforge.net) provides high quality 2D plotting for
 Python. Matplotlib can produce plots on screen using a variety of GUI
 toolkits, including Tk, GTK and WXPython. It also provides a number of
 commands useful for scientific computing, all with a syntax compatible
 with that of the popular Matlab program.
 
-IPython accepts the special option -pylab (Sec. `Command line
-options`_). This configures it to support matplotlib, honoring the
-settings in the .matplotlibrc file. IPython will detect the user's
-choice of matplotlib GUI backend, and automatically select the proper
-threading model to prevent blocking. It also sets matplotlib in
-interactive mode and modifies %run slightly, so that any
-matplotlib-based script can be executed using %run and the final
-show() command does not block the interactive shell.
-
-The -pylab option must be given first in order for IPython to
-configure its threading mode. However, you can still issue other
-options afterwards. This allows you to have a matplotlib-based
-environment customized with additional modules using the standard
-IPython profile mechanism (Sec. Profiles_): ''ipython -pylab -p
-myprofile'' will load the profile defined in ipythonrc-myprofile after
-configuring matplotlib.
-
-
+IPython accepts the special option -pylab (see :ref:`here
+<command_line_options>`). This configures it to support matplotlib, honoring
+the settings in the .matplotlibrc file. IPython will detect the user's choice
+of matplotlib GUI backend, and automatically select the proper threading model
+to prevent blocking. It also sets matplotlib in interactive mode and modifies
+%run slightly, so that any matplotlib-based script can be executed using %run
+and the final show() command does not block the interactive shell.
+
+The -pylab option must be given first in order for IPython to configure its
+threading mode. However, you can still issue other options afterwards. This
+allows you to have a matplotlib-based environment customized with additional
+modules using the standard IPython profile mechanism (see :ref:`here
+<profiles>`): ``ipython -pylab -p myprofile`` will load the profile defined in
+ipythonrc-myprofile after configuring matplotlib.

docs/source/interactive/tutorial.txt

@@ -1,315 +1,315
 .. _tutorial:
 
 ======================
 Quick IPython tutorial
 ======================
 
-.. contents::
-
 IPython can be used as an improved replacement for the Python prompt,
 and for that you don't really need to read any more of this manual. But
 in this section we'll try to summarize a few tips on how to make the
 most effective use of it for everyday Python development, highlighting
 things you might miss in the rest of the manual (which is getting long).
 We'll give references to parts in the manual which provide more detail
 when appropriate.
 
 The following article by Jeremy Jones provides an introductory tutorial
 about IPython: http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
 
 Highlights
 ==========
 
 Tab completion
 --------------
 
 TAB-completion, especially for attributes, is a convenient way to explore the
-structure of any object you're dealing with. Simply type object_name.<TAB>
-and a list of the object's attributes will be printed (see readline_ for
-more). Tab completion also works on file and directory names, which combined
-with IPython's alias system allows you to do from within IPython many of the
-things you normally would need the system shell for.
+structure of any object you're dealing with. Simply type object_name.<TAB> and
+a list of the object's attributes will be printed (see :ref:`the readline
+section <readline>` for more). Tab completion also works on file and directory
+names, which combined with IPython's alias system allows you to do from within
+IPython many of the things you normally would need the system shell for.
 
 Explore your objects
 --------------------
 
 Typing object_name? will print all sorts of details about any object,
 including docstrings, function definition lines (for call arguments) and
 constructor details for classes. The magic commands %pdoc, %pdef, %psource
 and %pfile will respectively print the docstring, function definition line,
 full source code and the complete file for any object (when they can be
 found). If automagic is on (it is by default), you don't need to type the '%'
-explicitly. See sec. `dynamic object information`_ for more.
+explicitly. See :ref:`this section <dynamic_object_info>` for more.
 
 The `%run` magic command
 ------------------------
 
-The %run magic command allows you to run any python script and load all of
-its data directly into the interactive namespace. Since the file is re-read
-from disk each time, changes you make to it are reflected immediately (in
-contrast to the behavior of import). I rarely use import for code I am
-testing, relying on %run instead. See magic_ section for more on this and
-other magic commands, or type the name of any magic command and ? to get
-details on it. See also sec. dreload_ for a recursive reload command. %run
+The %run magic command allows you to run any python script and load all of its
+data directly into the interactive namespace. Since the file is re-read from
+disk each time, changes you make to it are reflected immediately (in contrast
+to the behavior of import). I rarely use import for code I am testing, relying
+on %run instead. See :ref:`this section <magic>` for more on this and other
+magic commands, or type the name of any magic command and ? to get details on
+it. See also :ref:`this section <dreload>` for a recursive reload command. %run
 also has special flags for timing the execution of your scripts (-t) and for
 executing them under the control of either Python's pdb debugger (-d) or
 profiler (-p). With all of these, %run can be used as the main tool for
 efficient interactive development of code which you write in your editor of
 choice.
 
 Debug a Python script
 ---------------------
 
-Use the Python debugger, pdb. The %pdb command allows you to toggle on and
-off the automatic invocation of an IPython-enhanced pdb debugger (with
-coloring, tab completion and more) at any uncaught exception. The advantage
-of this is that pdb starts inside the function where the exception occurred,
-with all data still available. You can print variables, see code, execute
-statements and even walk up and down the call stack to track down the true
-source of the problem (which often is many layers in the stack above where
-the exception gets triggered). Running programs with %run and pdb active can
-be an efficient to develop and debug code, in many cases eliminating the need
-for print statements or external debugging tools. I often simply put a 1/0 in
-a place where I want to take a look so that pdb gets called, quickly view
-whatever variables I need to or test various pieces of code and then remove
-the 1/0. Note also that '%run -d' activates pdb and automatically sets
-initial breakpoints for you to step through your code, watch variables, etc.
-See Sec. `Output caching`_ for details.
+Use the Python debugger, pdb. The %pdb command allows you to toggle on and off
+the automatic invocation of an IPython-enhanced pdb debugger (with coloring,
+tab completion and more) at any uncaught exception. The advantage of this is
+that pdb starts inside the function where the exception occurred, with all data
+still available. You can print variables, see code, execute statements and even
+walk up and down the call stack to track down the true source of the problem
+(which often is many layers in the stack above where the exception gets
+triggered). Running programs with %run and pdb active can be an efficient to
+develop and debug code, in many cases eliminating the need for print statements
+or external debugging tools. I often simply put a 1/0 in a place where I want
+to take a look so that pdb gets called, quickly view whatever variables I need
+to or test various pieces of code and then remove the 1/0. Note also that '%run
+-d' activates pdb and automatically sets initial breakpoints for you to step
+through your code, watch variables, etc.  The :ref:`output caching section
+<output_caching>` has more details.
 
 Use the output cache
 --------------------
 
 All output results are automatically stored in a global dictionary named Out
 and variables named _1, _2, etc. alias them. For example, the result of input
 line 4 is available either as Out[4] or as _4. Additionally, three variables
 named _, __ and ___ are always kept updated with the for the last three
 results. This allows you to recall any previous result and further use it for
-new calculations. See Sec. `Output caching`_ for more.
+new calculations. See :ref:`the output caching section <output_caching>` for
+more.
 
 Suppress output
 ---------------
 
 Put a ';' at the end of a line to suppress the printing of output. This is
 useful when doing calculations which generate long output you are not
 interested in seeing. The _* variables and the Out[] list do get updated with
 the contents of the output, even if it is not printed. You can thus still
 access the generated results this way for further processing.
 
 Input cache
 -----------
 
 A similar system exists for caching input. All input is stored in a global
 list called In , so you can re-execute lines 22 through 28 plus line 34 by
 typing 'exec In[22:29]+In[34]' (using Python slicing notation). If you need
 to execute the same set of lines often, you can assign them to a macro with
-the %macro function. See sec. `Input caching`_ for more.
+the %macro function. See :ref:`here <input_caching>` for more.
 
 Use your input history
 ----------------------
 
 The %hist command can show you all previous input, without line numbers if
 desired (option -n) so you can directly copy and paste code either back in
 IPython or in a text editor. You can also save all your history by turning on
 logging via %logstart; these logs can later be either reloaded as IPython
 sessions or used as code for your programs.
 
 Define your own system aliases
 ------------------------------
 
 Even though IPython gives you access to your system shell via the ! prefix,
 it is convenient to have aliases to the system commands you use most often.
 This allows you to work seamlessly from inside IPython with the same commands
 you are used to in your system shell. IPython comes with some pre-defined
 aliases and a complete system for changing directories, both via a stack (see
 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
 visited directories and allows you to go to any previously visited one.
 
 Call system shell commands
 --------------------------
 
 Use Python to manipulate the results of system commands. The '!!' special
 syntax, and the %sc and %sx magic commands allow you to capture system output
 into Python variables.
 
 Use Python variables when calling the shell
 -------------------------------------------
 
-Expand python variables when calling the shell (either via '!' and '!!' or
-via aliases) by prepending a $ in front of them. You can also expand complete
-python expressions. See `System shell access`_ for more.
+Expand python variables when calling the shell (either via '!' and '!!' or via
+aliases) by prepending a $ in front of them. You can also expand complete
+python expressions. See :ref:`our shell section <system_shell_access>` for
+more details.
 
 Use profiles
 ------------
 
 Use profiles to maintain different configurations (modules to load, function
 definitions, option settings) for particular tasks. You can then have
-customized versions of IPython for specific purposes. See sec. profiles_ for
-more.
+customized versions of IPython for specific purposes. :ref:`This section
+<profiles>` has more details.
 
 
 Embed IPython in your programs
 ------------------------------
 
 A few lines of code are enough to load a complete IPython inside your own
 programs, giving you the ability to work with your data interactively after
-automatic processing has been completed. See sec. embedding_ for more.
+automatic processing has been completed. See :ref:`here <embedding>` for more.
 
 Use the Python profiler
 -----------------------
 
 When dealing with performance issues, the %run command with a -p option
 allows you to run complete programs under the control of the Python profiler.
 The %prun command does a similar job for single Python expressions (like
 function calls).
 
 Use IPython to present interactive demos
 ----------------------------------------
 
 Use the IPython.demo.Demo class to load any Python script as an interactive
-demo. With a minimal amount of simple markup, you can control the execution
-of the script, stopping as needed. See sec. `interactive demos`_ for more.
+demo. With a minimal amount of simple markup, you can control the execution of
+the script, stopping as needed. See :ref:`here <interactive_demos>` for more.
 
 Run doctests
 ------------
 
 Run your doctests from within IPython for development and debugging. The
 special %doctest_mode command toggles a mode where the prompt, output and
 exceptions display matches as closely as possible that of the default Python
 interpreter. In addition, this mode allows you to directly paste in code that
 contains leading '>>>' prompts, even if they have extra leading whitespace
 (as is common in doctest files). This combined with the '%history -tn' call
 to see your translated history (with these extra prompts removed and no line
 numbers) allows for an easy doctest workflow, where you can go from doctest
 to interactive execution to pasting into valid Python code as needed.
 
 Source code handling tips
 =========================
 
 IPython is a line-oriented program, without full control of the
 terminal. Therefore, it doesn't support true multiline editing. However,
 it has a number of useful tools to help you in dealing effectively with
 more complex editing.
 
 The %edit command gives a reasonable approximation of multiline editing,
 by invoking your favorite editor on the spot. IPython will execute the
 code you type in there as if it were typed interactively. Type %edit?
 for the full details on the edit command.
 
 If you have typed various commands during a session, which you'd like to
 reuse, IPython provides you with a number of tools. Start by using %hist
 to see your input history, so you can see the line numbers of all input.
 Let us say that you'd like to reuse lines 10 through 20, plus lines 24
 and 28. All the commands below can operate on these with the syntax::
 
     %command 10-20 24 28 
 
 where the command given can be:
 
     * %macro <macroname>: this stores the lines into a variable which,
       when called at the prompt, re-executes the input. Macros can be
       edited later using '%edit macroname', and they can be stored
       persistently across sessions with '%store macroname' (the storage
       system is per-profile). The combination of quick macros,
       persistent storage and editing, allows you to easily refine
       quick-and-dirty interactive input into permanent utilities, always
       available both in IPython and as files for general reuse.
     * %edit: this will open a text editor with those lines pre-loaded
       for further modification. It will then execute the resulting
       file's contents as if you had typed it at the prompt.
     * %save <filename>: this saves the lines directly to a named file on
       disk.
 
 While %macro saves input lines into memory for interactive re-execution,
 sometimes you'd like to save your input directly to a file. The %save
 magic does this: its input sytnax is the same as %macro, but it saves
 your input directly to a Python file. Note that the %logstart command
 also saves input, but it logs all input to disk (though you can
 temporarily suspend it and reactivate it with %logoff/%logon); %save
 allows you to select which lines of input you need to save.
 
 
 Lightweight 'version control'
 =============================
 
 When you call %edit with no arguments, IPython opens an empty editor
 with a temporary file, and it returns the contents of your editing
 session as a string variable. Thanks to IPython's output caching
 mechanism, this is automatically stored::
 
     In [1]: %edit
 
     IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
 
     Editing... done. Executing edited code...
 
     hello - this is a temporary file
 
     Out[1]: "print 'hello - this is a temporary file'\n"
 
 Now, if you call '%edit -p', IPython tries to open an editor with the
 same data as the last time you used %edit. So if you haven't used %edit
 in the meantime, this same contents will reopen; however, it will be
 done in a new file. This means that if you make changes and you later
 want to find an old version, you can always retrieve it by using its
 output number, via '%edit _NN', where NN is the number of the output
 prompt.
 
 Continuing with the example above, this should illustrate this idea::
 
     In [2]: edit -p
 
     IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
 
     Editing... done. Executing edited code...
 
     hello - now I made some changes
 
     Out[2]: "print 'hello - now I made some changes'\n"
 
     In [3]: edit _1
 
     IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
 
     Editing... done. Executing edited code...
 
     hello - this is a temporary file
 
     IPython version control at work :)
 
     Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
 
 
 This section was written after a contribution by Alexander Belchenko on
 the IPython user list.
 
 
 Effective logging
 =================
 
 A very useful suggestion sent in by Robert Kern follows:
 
 I recently happened on a nifty way to keep tidy per-project log files. I
 made a profile for my project (which is called "parkfield")::
 
     include ipythonrc
 
     # cancel earlier logfile invocation:
 
     logfile ''
 
     execute import time
 
     execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
 
     execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
 
 I also added a shell alias for convenience::
 
     alias parkfield="ipython -pylab -profile parkfield" 
 
 Now I have a nice little directory with everything I ever type in,
 organized by project and date.
 
 Contribute your own: If you have your own favorite tip on using IPython
 efficiently for a certain task (especially things which can't be done in
 the normal Python interpreter), don't hesitate to send it!

docs/source/license_and_copyright.txt

@@ -1,61 +1,91
 .. _license:
 
-=============================
-License and Copyright 
-=============================
+=====================
+License and Copyright
+=====================
 
-This files needs to be updated to reflect what the new COPYING.txt files says about our license and copyright!
+License
+=======
 
-IPython is released under the terms of the BSD license, whose general
-form can be found at: http://www.opensource.org/licenses/bsd-license.php. The full text of the
-IPython license is reproduced below::
+IPython is licensed under the terms of the new or revised BSD license, as follows::
 
-    IPython is released under a BSD-type license.
-
-    Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez
-    <[e-mail]>.
-
-    Copyright (c) 2001 Janko Hauser <[e-mail]> and  
-    Nathaniel Gray <[e-mail]>.
+    Copyright (c) 2008, IPython Development Team
 
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    a. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-
-    b. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
-
-    c. Neither the name of the copyright holders nor the names of any
-    contributors to this software may be used to endorse or promote
-    products derived from this software without specific prior written
-    permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
-    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
-    REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
-    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
-    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-    POSSIBILITY OF SUCH DAMAGE. 
-
-Individual authors are the holders of the copyright for their code and
-are listed in each file.
+    modification, are permitted provided that the following conditions are
+    met:
+
+    Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+    Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+    Neither the name of the IPython Development Team nor the names of its
+    contributors may be used to endorse or promote products derived from this
+    software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+    IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+About the IPython Development Team
+==================================
+
+Fernando Perez began IPython in 2001 based on code from Janko Hauser
+<[e-mail]> and Nathaniel Gray <[e-mail]>. Fernando is still
+the project lead.
+
+The IPython Development Team is the set of all contributors to the IPython
+project. This includes all of the IPython subprojects. Here is a list of the
+currently active contributors:
+
+	* Matthieu Brucher
+	* Ondrej Certik
+	* Laurent Dufrechou
+	* Robert Kern
+	* Brian E. Granger
+	* Fernando Perez (project leader)
+	* Benjamin Ragan-Kelley
+	* Ville M. Vainio
+	* Gael Varoququx
+	* Stefan van der Walt
+	* Tech-X Corporation
+	* Barry Wark
+
+If your name is missing, please add it.  
+
+Our Copyright Policy
+====================
+
+IPython uses a shared copyright model. Each contributor maintains copyright
+over their contributions to IPython. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the
+IPython source code, in its entirety is not the copyright of any single person
+or institution. Instead, it is the collective copyright of the entire IPython
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the IPython repositories.
+
+Miscellaneous
+=============
 
 Some files (DPyGetOpt.py, for example) may be licensed under different
-conditions. Ultimately each file indicates clearly the conditions under
-which its author/authors have decided to publish the code.
+conditions. Ultimately each file indicates clearly the conditions under which
+its author/authors have decided to publish the code.
 
-Versions of IPython up to and including 0.6.3 were released under the
-GNU Lesser General Public License (LGPL), available at
+Versions of IPython up to and including 0.6.3 were released under the GNU
+Lesser General Public License (LGPL), available at
 http://www.gnu.org/copyleft/lesser.html.
  No newline at end of file

docs/source/overview.txt

@@ -1,174 +1,233
 .. _overview:
 
 ============
 Introduction
 ============
 
 Overview
 ========
 
 One of Python's most useful features is its interactive interpreter.
 This system allows very fast testing of ideas without the overhead of
 creating test files as is typical in most programming languages.
 However, the interpreter supplied with the standard Python distribution
 is somewhat limited for extended interactive use.
 
 The goal of IPython is to create a comprehensive environment for
-interactive and exploratory computing.  To support, this goal, IPython
+interactive and exploratory computing.  To support this goal, IPython
 has two main components:
 
-	* An enhanced interactive Python shell.
-	* An architecture for interactive parallel computing.
+* An enhanced interactive Python shell.
+* An architecture for interactive parallel computing.
 
 All of IPython is open source (released under the revised BSD license).
 
 Enhanced interactive Python shell
 =================================
 
-IPython's interactive shell (`ipython`), has the following goals:
-
-   1. Provide an interactive shell superior to Python's default. IPython
-      has many features for object introspection, system shell access,
-      and its own special command system for adding functionality when
-      working interactively. It tries to be a very efficient environment
-      both for Python code development and for exploration of problems
-      using Python objects (in situations like data analysis).
-   2. Serve as an embeddable, ready to use interpreter for your own
-      programs. IPython can be started with a single call from inside
-      another program, providing access to the current namespace. This
-      can be very useful both for debugging purposes and for situations
-      where a blend of batch-processing and interactive exploration are
-      needed.
-   3. Offer a flexible framework which can be used as the base
-      environment for other systems with Python as the underlying
-      language. Specifically scientific environments like Mathematica,
-      IDL and Matlab inspired its design, but similar ideas can be
-      useful in many fields.
-   4. Allow interactive testing of threaded graphical toolkits. IPython
-      has support for interactive, non-blocking control of GTK, Qt and
-      WX applications via special threading flags. The normal Python
-      shell can only do this for Tkinter applications.
+IPython's interactive shell (:command:`ipython`), has the following goals,
+amongst others:
+
+1. Provide an interactive shell superior to Python's default. IPython
+   has many features for object introspection, system shell access,
+   and its own special command system for adding functionality when
+   working interactively. It tries to be a very efficient environment
+   both for Python code development and for exploration of problems
+   using Python objects (in situations like data analysis).
+  
+2. Serve as an embeddable, ready to use interpreter for your own
+   programs. IPython can be started with a single call from inside
+   another program, providing access to the current namespace. This
+   can be very useful both for debugging purposes and for situations
+   where a blend of batch-processing and interactive exploration are
+   needed.  New in the 0.9 version of IPython is a reusable wxPython
+   based IPython widget.
+  
+3. Offer a flexible framework which can be used as the base
+   environment for other systems with Python as the underlying
+   language. Specifically scientific environments like Mathematica,
+   IDL and Matlab inspired its design, but similar ideas can be
+   useful in many fields.
+  
+4. Allow interactive testing of threaded graphical toolkits. IPython
+   has support for interactive, non-blocking control of GTK, Qt and
+   WX applications via special threading flags. The normal Python
+   shell can only do this for Tkinter applications.
 
 Main features of the interactive shell
 --------------------------------------
 
-	* Dynamic object introspection. One can access docstrings, function
-	  definition prototypes, source code, source files and other details
-	  of any object accessible to the interpreter with a single
-	  keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
-	* Searching through modules and namespaces with :samp:`*` wildcards, both
-	  when using the :samp:`?` system and via the :samp:`%psearch` command.
-	* Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
-	  This works for keywords, modules, methods, variables and files in the
-	  current directory. This is supported via the readline library, and
-	  full access to configuring readline's behavior is provided. 
-	  Custom completers can be implemented easily for different purposes
-	  (system commands, magic arguments etc.)
-	* Numbered input/output prompts with command history (persistent
-	  across sessions and tied to each profile), full searching in this
-	  history and caching of all input and output.
-	* User-extensible 'magic' commands. A set of commands prefixed with
-	  :samp:`%` is available for controlling IPython itself and provides
-	  directory control, namespace information and many aliases to
-	  common system shell commands.
-	* Alias facility for defining your own system aliases.
-	* Complete system shell access. Lines starting with :samp:`!` are passed
-	  directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` 
-	  captures shell output into python variables for further use.
-	* Background execution of Python commands in a separate thread.
-	  IPython has an internal job manager called jobs, and a
-	  conveninence backgrounding magic function called :samp:`%bg`.
-	* The ability to expand python variables when calling the system
-	  shell. In a shell command, any python variable prefixed with :samp:`$` is
-	  expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for
-	  access to shell and environment variables like :envvar:`PATH`).
-	* Filesystem navigation, via a magic :samp:`%cd` command, along with a
-	  persistent bookmark system (using :samp:`%bookmark`) for fast access to
-	  frequently visited directories.
-	* A lightweight persistence framework via the :samp:`%store` command, which
-	  allows you to save arbitrary Python variables. These get restored
-	  automatically when your session restarts.
-	* Automatic indentation (optional) of code as you type (through the
-	  readline library).
-	* Macro system for quickly re-executing multiple lines of previous
-	  input with a single name. Macros can be stored persistently via
-	  :samp:`%store` and edited via :samp:`%edit`.
-	* Session logging (you can then later use these logs as code in your
-	  programs). Logs can optionally timestamp all input, and also store
-	  session output (marked as comments, so the log remains valid
-	  Python source code).
-	* Session restoring: logs can be replayed to restore a previous
-	  session to the state where you left it.
-	* Verbose and colored exception traceback printouts. Easier to parse
-	  visually, and in verbose mode they produce a lot of useful
-	  debugging information (basically a terminal version of the cgitb
-	  module).
-	* Auto-parentheses: callable objects can be executed without
-	  parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
-	* Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
-	  auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
-	  automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
-	  becomes :samp:`my_function("a b")`.
-	* Extensible input syntax. You can define filters that pre-process
-	  user input to simplify input in special situations. This allows
-	  for example pasting multi-line code fragments which start with
-	  :samp:`>>>` or :samp:`...` such as those from other python sessions or the
-	  standard Python documentation.
-	* Flexible configuration system. It uses a configuration file which
-	  allows permanent setting of all command-line options, module
-	  loading, code and file execution. The system allows recursive file
-	  inclusion, so you can have a base file with defaults and layers
-	  which load other customizations for particular projects.
-	* Embeddable. You can call IPython as a python shell inside your own
-	  python programs. This can be used both for debugging code or for
-	  providing interactive abilities to your programs with knowledge
-	  about the local namespaces (very useful in debugging and data
-	  analysis situations).
-	* Easy debugger access. You can set IPython to call up an enhanced
-	  version of the Python debugger (pdb) every time there is an
-	  uncaught exception. This drops you inside the code which triggered
-	  the exception with all the data live and it is possible to
-	  navigate the stack to rapidly isolate the source of a bug. The
-	  :samp:`%run` magic command (with the :samp:`-d` option) can run any script under
-	  pdb's control, automatically setting initial breakpoints for you.
-	  This version of pdb has IPython-specific improvements, including
-	  tab-completion and traceback coloring support. For even easier
-	  debugger access, try :samp:`%debug` after seeing an exception. winpdb is 
-	  also supported, see ipy_winpdb extension.
-	* Profiler support. You can run single statements (similar to
-	  :samp:`profile.run()`) or complete programs under the profiler's control.
-	  While this is possible with standard cProfile or profile modules,
-	  IPython wraps this functionality with magic commands (see :samp:`%prun`
-	  and :samp:`%run -p`) convenient for rapid interactive work.
-	* Doctest support. The special :samp:`%doctest_mode` command toggles a mode
-	  that allows you to paste existing doctests (with leading :samp:`>>>`
-	  prompts and whitespace) and uses doctest-compatible prompts and
-	  output, so you can use IPython sessions as doctest code.
+* Dynamic object introspection. One can access docstrings, function
+  definition prototypes, source code, source files and other details
+  of any object accessible to the interpreter with a single
+  keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
+  
+* Searching through modules and namespaces with :samp:`*` wildcards, both
+  when using the :samp:`?` system and via the :samp:`%psearch` command.
+
+* Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
+  This works for keywords, modules, methods, variables and files in the
+  current directory. This is supported via the readline library, and
+  full access to configuring readline's behavior is provided. 
+  Custom completers can be implemented easily for different purposes
+  (system commands, magic arguments etc.)
+
+* Numbered input/output prompts with command history (persistent
+  across sessions and tied to each profile), full searching in this
+  history and caching of all input and output.
+
+* User-extensible 'magic' commands. A set of commands prefixed with
+  :samp:`%` is available for controlling IPython itself and provides
+  directory control, namespace information and many aliases to
+  common system shell commands.
+
+* Alias facility for defining your own system aliases.
+
+* Complete system shell access. Lines starting with :samp:`!` are passed
+  directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` 
+  captures shell output into python variables for further use.
+
+* Background execution of Python commands in a separate thread.
+  IPython has an internal job manager called jobs, and a
+  convenience backgrounding magic function called :samp:`%bg`.
+
+* The ability to expand python variables when calling the system
+  shell. In a shell command, any python variable prefixed with :samp:`$` is
+  expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for
+  access to shell and environment variables like :envvar:`PATH`).
+
+* Filesystem navigation, via a magic :samp:`%cd` command, along with a
+  persistent bookmark system (using :samp:`%bookmark`) for fast access to
+  frequently visited directories.
+
+* A lightweight persistence framework via the :samp:`%store` command, which
+  allows you to save arbitrary Python variables. These get restored
+  automatically when your session restarts.
+
+* Automatic indentation (optional) of code as you type (through the
+  readline library).
+
+* Macro system for quickly re-executing multiple lines of previous
+  input with a single name. Macros can be stored persistently via
+  :samp:`%store` and edited via :samp:`%edit`.
+
+* Session logging (you can then later use these logs as code in your
+  programs). Logs can optionally timestamp all input, and also store
+  session output (marked as comments, so the log remains valid
+  Python source code).
+
+* Session restoring: logs can be replayed to restore a previous
+  session to the state where you left it.
+
+* Verbose and colored exception traceback printouts. Easier to parse
+  visually, and in verbose mode they produce a lot of useful
+  debugging information (basically a terminal version of the cgitb
+  module).
+
+* Auto-parentheses: callable objects can be executed without
+  parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
+
+* Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
+  auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
+  automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
+  becomes :samp:`my_function("a b")`.
+
+* Extensible input syntax. You can define filters that pre-process
+  user input to simplify input in special situations. This allows
+  for example pasting multi-line code fragments which start with
+  :samp:`>>>` or :samp:`...` such as those from other python sessions or the
+  standard Python documentation.
+
+* Flexible configuration system. It uses a configuration file which
+  allows permanent setting of all command-line options, module
+  loading, code and file execution. The system allows recursive file
+  inclusion, so you can have a base file with defaults and layers
+  which load other customizations for particular projects.
+
+* Embeddable. You can call IPython as a python shell inside your own
+  python programs. This can be used both for debugging code or for
+  providing interactive abilities to your programs with knowledge
+  about the local namespaces (very useful in debugging and data
+  analysis situations).
+
+* Easy debugger access. You can set IPython to call up an enhanced
+  version of the Python debugger (pdb) every time there is an
+  uncaught exception. This drops you inside the code which triggered
+  the exception with all the data live and it is possible to
+  navigate the stack to rapidly isolate the source of a bug. The
+  :samp:`%run` magic command (with the :samp:`-d` option) can run any script under
+  pdb's control, automatically setting initial breakpoints for you.
+  This version of pdb has IPython-specific improvements, including
+  tab-completion and traceback coloring support. For even easier
+  debugger access, try :samp:`%debug` after seeing an exception. winpdb is 
+  also supported, see ipy_winpdb extension.
+
+* Profiler support. You can run single statements (similar to
+  :samp:`profile.run()`) or complete programs under the profiler's control.
+  While this is possible with standard cProfile or profile modules,
+  IPython wraps this functionality with magic commands (see :samp:`%prun`
+  and :samp:`%run -p`) convenient for rapid interactive work.
+
+* Doctest support. The special :samp:`%doctest_mode` command toggles a mode
+  that allows you to paste existing doctests (with leading :samp:`>>>`
+  prompts and whitespace) and uses doctest-compatible prompts and
+  output, so you can use IPython sessions as doctest code.
 
 Interactive parallel computing
 ==============================
 
 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and supercomputers, is becoming ubiquitous. Over the last 3 years, we have developed an
 architecture within IPython that allows such hardware to be used quickly and easily
 from Python. Moreover, this architecture is designed to support interactive and
 collaborative parallel computing.
 
+The main features of this system are:
+
+* Quickly parallelize Python code from an interactive Python/IPython session.
+
+* A flexible and dynamic process model that be deployed on anything from 
+  multicore workstations to supercomputers.
+
+* An architecture that supports many different styles of parallelism, from
+  message passing to task farming.  And all of these styles can be handled
+  interactively.
+
+* Both blocking and fully asynchronous interfaces.
+
+* High level APIs that enable many things to be parallelized in a few lines
+  of code.
+
+* Write parallel code that will run unchanged on everything from multicore
+  workstations to supercomputers.
+
+* Full integration with Message Passing libraries (MPI).
+
+* Capabilities based security model with full encryption of network connections.
+
+* Share live parallel jobs with other users securely.  We call this collaborative
+  parallel computing.
+
+* Dynamically load balanced task farming system.
+
+* Robust error handling.  Python exceptions raised in parallel execution are
+  gathered and presented to the top-level code.
+
 For more information, see our :ref:`overview <parallel_index>` of using IPython for
 parallel computing.
 
 Portability and Python requirements
 -----------------------------------
 
 As of the 0.9 release, IPython requires Python 2.4 or greater.  We have
 not begun to test IPython on Python 2.6 or 3.0, but we expect it will
 work with some minor changes.
 
 IPython is known to work on the following operating systems:
 
 	* Linux
 	* AIX
 	* Most other Unix-like OSs (Solaris, BSD, etc.)
 	* Mac OS X
 	* Windows (CygWin, XP, Vista, etc.)
 
 See :ref:`here <install_index>` for instructions on how to install IPython.
  No newline at end of file

docs/source/parallel/index.txt

@@ -1,17 +1,16
 .. _parallel_index:
 
 ====================================
-Using IPython for Parallel computing
+Using IPython for parallel computing
 ====================================
 
-User Documentation
-==================
-
 .. toctree::
    :maxdepth: 2
 
    parallel_intro.txt
+   parallel_process.txt
    parallel_multiengine.txt
    parallel_task.txt
    parallel_mpi.txt
+   parallel_security.txt
 

docs/source/parallel/parallel_intro.txt

@@ -1,242 +1,205
 .. _ip1par:
 
-======================================
-Using IPython for parallel computing
-======================================
-
-.. contents::
+============================
+Overview and getting started
+============================
 
 Introduction
 ============
 
-This file gives an overview of IPython. IPython has a sophisticated and
-powerful architecture for parallel and distributed computing. This
-architecture abstracts out parallelism in a very general way, which
-enables IPython to support many different styles of parallelism
-including:
+This section gives an overview of IPython's sophisticated and powerful
+architecture for parallel and distributed computing. This architecture
+abstracts out parallelism in a very general way, which enables IPython to
+support many different styles of parallelism including:
 
-	* Single program, multiple data (SPMD) parallelism.
-	* Multiple program, multiple data (MPMD) parallelism.
-	* Message passing using ``MPI``.
-	* Task farming.
-	* Data parallel.
-	* Combinations of these approaches.
-	* Custom user defined approaches.
+* Single program, multiple data (SPMD) parallelism.
+* Multiple program, multiple data (MPMD) parallelism.
+* Message passing using MPI.
+* Task farming.
+* Data parallel.
+* Combinations of these approaches.
+* Custom user defined approaches.
 
 Most importantly, IPython enables all types of parallel applications to
 be developed, executed, debugged and monitored *interactively*. Hence,
 the ``I`` in IPython.  The following are some example usage cases for IPython:
 
-	* Quickly parallelize algorithms that are embarrassingly parallel
-	  using a number of simple approaches.  Many simple things can be
-	  parallelized interactively in one or two lines of code.
-	* Steer traditional MPI applications on a supercomputer from an
-	  IPython session on your laptop.
-	* Analyze and visualize large datasets (that could be remote and/or
-	  distributed) interactively using IPython and tools like
-	  matplotlib/TVTK.
-	* Develop, test and debug new parallel algorithms 
-	  (that may use MPI) interactively.
-	* Tie together multiple MPI jobs running on different systems into
-	  one giant distributed and parallel system.
-	* Start a parallel job on your cluster and then have a remote 	
-	  collaborator connect to it and pull back data into their 
-	  local IPython session for plotting and analysis.
-	* Run a set of tasks on a set of CPUs using dynamic load balancing.
+* Quickly parallelize algorithms that are embarrassingly parallel
+  using a number of simple approaches.  Many simple things can be
+  parallelized interactively in one or two lines of code.
+
+* Steer traditional MPI applications on a supercomputer from an
+  IPython session on your laptop.
+
+* Analyze and visualize large datasets (that could be remote and/or
+  distributed) interactively using IPython and tools like
+  matplotlib/TVTK.
+
+* Develop, test and debug new parallel algorithms 
+  (that may use MPI) interactively.
+
+* Tie together multiple MPI jobs running on different systems into
+  one giant distributed and parallel system.
+
+* Start a parallel job on your cluster and then have a remote 	
+  collaborator connect to it and pull back data into their 
+  local IPython session for plotting and analysis.
+
+* Run a set of tasks on a set of CPUs using dynamic load balancing.
 
 Architecture overview
 =====================
 
 The IPython architecture consists of three components:
 
-	* The IPython engine.
-	* The IPython controller.
-	* Various controller Clients.
+* The IPython engine.
+* The IPython controller.
+* Various controller clients.
+
+These components live in the :mod:`IPython.kernel` package and are
+installed with IPython.  They do, however, have additional dependencies
+that must be installed.  For more information, see our
+:ref:`installation documentation <install_index>`.
 
 IPython engine
 ---------------
 
 The IPython engine is a Python instance that takes Python commands over a
 network connection. Eventually, the IPython engine will be a full IPython
 interpreter, but for now, it is a regular Python interpreter. The engine
 can also handle incoming and outgoing Python objects sent over a network
 connection.  When multiple engines are started, parallel and distributed
 computing becomes possible. An important feature of an IPython engine is
 that it blocks while user code is being executed. Read on for how the
 IPython controller solves this problem to expose a clean asynchronous API
 to the user.
 
 IPython controller
 ------------------
 
 The IPython controller provides an interface for working with a set of
 engines. At an general level, the controller is a process to which
 IPython engines can connect. For each connected engine, the controller
 manages a queue. All actions that can be performed on the engine go
 through this queue. While the engines themselves block when user code is
 run, the controller hides that from the user to provide a fully
-asynchronous interface to a set of engines. Because the controller
-listens on a network port for engines to connect to it, it must be
-started before any engines are started.  
+asynchronous interface to a set of engines. 
+
+.. note::
+
+    Because the controller listens on a network port for engines to 
+    connect to it, it must be started *before* any engines are started.  
 
 The controller also provides a single point of contact for users who wish
 to utilize the engines connected to the controller. There are different
 ways of working with a controller. In IPython these ways correspond to different interfaces that the controller is adapted to.  Currently we have two default interfaces to the controller: 
 
-	* The MultiEngine interface.
-	* The Task interface.
+* The MultiEngine interface, which provides the simplest possible way of
+  working with engines interactively.
+* The Task interface, which provides presents the engines as a load balanced
+  task farming system.
 
 Advanced users can easily add new custom interfaces to enable other
 styles of parallelism. 
 
 .. note:: 
 
 	A single controller and set of engines can be accessed 
 	through multiple interfaces simultaneously.  This opens the
 	door for lots of interesting things.  
 
 Controller clients
 ------------------
 
 For each controller interface, there is a corresponding client. These
 clients allow users to interact with a set of engines through the
-interface.
+interface.  Here are the two default clients:
+
+* The :class:`MultiEngineClient` class.
+* The :class:`TaskClient` class.
 
 Security
 --------
 
-By default (as long as `pyOpenSSL` is installed) all network connections between the controller and engines and the controller and clients are secure.  What does this mean?  First of all, all of the connections will be encrypted using SSL.  Second, the connections are authenticated.  We handle authentication in a `capabilities`__ based security model.  In this model,  a "capability (known in some systems as a key) is a communicable, unforgeable token of authority".  Put simply, a capability is like a key to your house.  If you have the key to your house, you can get in, if not you can't.  
-
-.. __: http://en.wikipedia.org/wiki/Capability-based_security
+By default (as long as `pyOpenSSL` is installed) all network connections between the controller and engines and the controller and clients are secure.  What does this mean?  First of all, all of the connections will be encrypted using SSL.  Second, the connections are authenticated.  We handle authentication in a capability based security model [Capability]_.  In this model,  a "capability (known in some systems as a key) is a communicable, unforgeable token of authority".  Put simply, a capability is like a key to your house.  If you have the key to your house, you can get in.  If not, you can't.  
 
-In our architecture, the controller is the only process that listens on network ports, and is thus responsible to creating these keys.  In IPython, these keys are known as Foolscap URLs, or FURLs, because of the underlying network protocol we are using.  As a user, you don't need to know anything about the details of these FURLs, other than that when the controller starts, it saves a set of FURLs to files named something.furl.  The default location of these files is your ~./ipython directory.
+In our architecture, the controller is the only process that listens on network ports, and is thus responsible to creating these keys.  In IPython, these keys are known as Foolscap URLs, or FURLs, because of the underlying network protocol we are using.  As a user, you don't need to know anything about the details of these FURLs, other than that when the controller starts, it saves a set of FURLs to files named :file:`something.furl`.  The default location of these files is the :file:`~./ipython/security` directory.
 
-To connect and authenticate to the controller an engine or client simply needs to present an appropriate furl (that was originally created by the controller) to the controller.  Thus, the .furl files need to be copied to a location where the clients and engines can find them.  Typically, this is the ~./ipython directory on the host where the client/engine is running (which could be a different host than the controller).  Once the .furl files are copied over, everything should work fine.
+To connect and authenticate to the controller an engine or client simply needs to present an appropriate FURL (that was originally created by the controller) to the controller.  Thus, the FURL files need to be copied to a location where the clients and engines can find them.  Typically, this is the :file:`~./ipython/security` directory on the host where the client/engine is running (which could be a different host than the controller).  Once the FURL files are copied over, everything should work fine.
 
-Getting Started
-===============
-
-To use IPython for parallel computing, you need to start one instance of
-the controller and one or more instances of the engine. The controller
-and each engine can run on different machines or on the same machine.
-Because of this, there are many different possibilities for setting up
-the IP addresses and ports used by the various processes.
-
-Starting the controller and engine on your local machine
---------------------------------------------------------
-
-This is the simplest configuration that can be used and is useful for
-testing the system and on machines that have multiple cores and/or
-multple CPUs. The easiest way of doing this is using the ``ipcluster``
-command::
+Currently, there are three FURL files that the controller creates:
 
-	$ ipcluster -n 4
-	
-This will start an IPython controller and then 4 engines that connect to
-the controller. Lastly, the script will print out the Python commands
-that you can use to connect to the controller. It is that easy.
-
-Underneath the hood, the ``ipcluster`` script uses two other top-level
-scripts that you can also use yourself. These scripts are
-``ipcontroller``, which starts the controller and ``ipengine`` which
-starts one engine. To use these scripts to start things on your local
-machine, do the following.
-
-First start the controller::
+ipcontroller-engine.furl
+    This FURL file is the key that gives an engine the ability to connect
+    to a controller.
 
-	$ ipcontroller &
-	
-Next, start however many instances of the engine you want using (repeatedly) the command::
-
-	$ ipengine &
+ipcontroller-tc.furl
+    This FURL file is the key that a :class:`TaskClient` must use to
+    connect to the task interface of a controller.
+    
+ipcontroller-mec.furl
+    This FURL file is the key that a :class:`MultiEngineClient` must use
+    to connect to the multiengine interface of a controller.
 
-.. warning:: 
-	
-	The order of the above operations is very important.  You *must*
- 	start the controller before the engines, since the engines connect 
-	to the controller as they get started.
+More details of how these FURL files are used are given below.
 
-On some platforms you may need to give these commands in the form
-``(ipcontroller &)`` and ``(ipengine &)`` for them to work properly. The
-engines should start and automatically connect to the controller on the
-default ports, which are chosen for this type of setup. You are now ready
-to use the controller and engines from IPython.
+A detailed description of the security model and its implementation in IPython
+can be found :ref:`here <parallelsecurity>`.
 
-Starting the controller and engines on different machines
----------------------------------------------------------
-
-This section needs to be updated to reflect the new Foolscap capabilities based
-model.
-
-Using ``ipcluster`` with ``ssh``
---------------------------------
-
-The ``ipcluster`` command can also start a controller and engines using
-``ssh``.  We need more documentation on this, but for now here is any
-example startup script::
-
-	controller = dict(host='myhost',
-	                  engine_port=None, # default is 10105
-	                  control_port=None,
-	                  )
-
-	# keys are hostnames, values are the number of engine on that host
-	engines = dict(node1=2,
-	               node2=2,
-	               node3=2,
-	               node3=2,
-	               )
-
-Starting engines using ``mpirun``
----------------------------------
-
-The IPython engines can be started using ``mpirun``/``mpiexec``, even if
-the engines don't call MPI_Init() or use the MPI API in any way. This is
-supported on modern MPI implementations like `Open MPI`_.. This provides
-an really nice way of starting a bunch of engine. On a system with MPI
-installed you can do::
-
-	mpirun -n 4 ipengine --controller-port=10000 --controller-ip=host0
-
-.. _Open MPI: http://www.open-mpi.org/
-
-More details on using MPI with IPython can be found :ref:`here <parallelmpi>`.
+Getting Started
+===============
 
-Log files
----------
+To use IPython for parallel computing, you need to start one instance of
+the controller and one or more instances of the engine. Initially, it is best to simply start a controller and engines on a single host using the :command:`ipcluster` command.  To start a controller and 4 engines on you localhost, just do::
 
-All of the components of IPython have log files associated with them.
-These log files can be extremely useful in debugging problems with
-IPython and can be found in the directory ``~/.ipython/log``.  Sending
-the log files to us will often help us to debug any problems.
+    $ ipcluster local -n 4
 
-Next Steps
-==========
+More details about starting the IPython controller and engines can be found :ref:`here <parallel_process>`
 
 Once you have started the IPython controller and one or more engines, you
-are ready to use the engines to do somnething useful. To make sure
-everything is working correctly, try the following commands::
+are ready to use the engines to do something useful. To make sure
+everything is working correctly, try the following commands:
+
+.. sourcecode:: ipython
 
 	In [1]: from IPython.kernel import client
 	
-	In [2]: mec = client.MultiEngineClient()    # This looks for .furl files in ~./ipython
+	In [2]: mec = client.MultiEngineClient()
 	
 	In [4]: mec.get_ids()
 	Out[4]: [0, 1, 2, 3]
 	
 	In [5]: mec.execute('print "Hello World"')
 	Out[5]: 
 	<Results List>
 	[0] In [1]: print "Hello World"
 	[0] Out[1]: Hello World
 
 	[1] In [1]: print "Hello World"
 	[1] Out[1]: Hello World
 
 	[2] In [1]: print "Hello World"
 	[2] Out[1]: Hello World
 
 	[3] In [1]: print "Hello World"
 	[3] Out[1]: Hello World
 
-If this works, you are ready to learn more about the :ref:`MultiEngine <parallelmultiengine>` and :ref:`Task <paralleltask>` interfaces to the controller.
+Remember, a client also needs to present a FURL file to the controller.  How does this happen?  When a multiengine client is created with no arguments, the client tries to find the corresponding FURL file in the local :file:`~./ipython/security` directory.  If it finds it, you are set.  If you have put the FURL file in a different location or it has a different name, create the client like this::
+
+    mec = client.MultiEngineClient('/path/to/my/ipcontroller-mec.furl')
+
+Same thing hold true of creating a task client::
+
+    tc = client.TaskClient('/path/to/my/ipcontroller-tc.furl')
+
+You are now ready to learn more about the :ref:`MultiEngine <parallelmultiengine>` and :ref:`Task <paralleltask>` interfaces to the controller.
+
+.. note:: 
+
+    Don't forget that the engine, multiengine client and task client all have
+    *different* furl files. You must move *each* of these around to an
+    appropriate location so that the engines and clients can use them to
+    connect to the controller.
+
+.. [Capability] Capability-based security, http://en.wikipedia.org/wiki/Capability-based_security
+

docs/source/parallel/parallel_mpi.txt

@@ -1,22 +1,157
 .. _parallelmpi:
 
 =======================
 Using MPI with IPython
 =======================
 
-The simplest way of getting started with MPI is to install an MPI implementation
-(we recommend `Open MPI`_) and `mpi4py`_ and then start the engines using the
-``mpirun`` command::
-
-	mpirun -n 4 ipengine --mpi=mpi4py
-	
-This will automatically import `mpi4py`_ and make sure that `MPI_Init` is called
-at the right time. We also have built in support for `PyTrilinos`_, which can be
-used (assuming `PyTrilinos`_ is installed) by starting the engines with::
-
-	mpirun -n 4 ipengine --mpi=pytrilinos
-
-.. _MPI: http://www-unix.mcs.anl.gov/mpi/
-.. _mpi4py: http://mpi4py.scipy.org/
-.. _Open MPI: http://www.open-mpi.org/
-.. _PyTrilinos: http://trilinos.sandia.gov/packages/pytrilinos/
  No newline at end of file
+Often, a parallel algorithm will require moving data between the engines.  One way of accomplishing this is by doing a pull and then a push using the multiengine client.  However, this will be slow as all the data has to go through the controller to the client and then back through the controller, to its final destination.
+
+A much better way of moving data between engines is to use a message passing library, such as the Message Passing Interface (MPI) [MPI]_.  IPython's parallel computing architecture has been designed from the ground up to integrate with MPI.  This document describes how to use MPI with IPython.
+
+Additional installation requirements
+====================================
+
+If you want to use MPI with IPython, you will need to install:
+
+* A standard MPI implementation such as OpenMPI [OpenMPI]_ or MPICH.
+* The mpi4py [mpi4py]_ package.
+
+.. note::
+
+    The mpi4py package is not a strict requirement. However, you need to
+    have *some* way of calling MPI from Python. You also need some way of
+    making sure that :func:`MPI_Init` is called when the IPython engines start
+    up. There are a number of ways of doing this and a good number of
+    associated subtleties. We highly recommend just using mpi4py as it
+    takes care of most of these problems. If you want to do something
+    different, let us know and we can help you get started.
+
+Starting the engines with MPI enabled
+=====================================
+
+To use code that calls MPI, there are typically two things that MPI requires.
+
+1. The process that wants to call MPI must be started using
+   :command:`mpirun` or a batch system (like PBS) that has MPI support.
+2. Once the process starts, it must call :func:`MPI_Init`.
+
+There are a couple of ways that you can start the IPython engines and get these things to happen.
+
+Automatic starting using :command:`mpirun` and :command:`ipcluster`
+-------------------------------------------------------------------
+
+The easiest approach is to use the `mpirun` mode of :command:`ipcluster`, which will first start a controller and then a set of engines using :command:`mpirun`::
+
+    $ ipcluster mpirun -n 4
+
+This approach is best as interrupting :command:`ipcluster` will automatically
+stop and clean up the controller and engines.
+
+Manual starting using :command:`mpirun`
+---------------------------------------
+
+If you want to start the IPython engines using the :command:`mpirun`, just do::
+
+    $ mpirun -n 4 ipengine --mpi=mpi4py
+
+This requires that you already have a controller running and that the FURL
+files for the engines are in place. We also have built in support for
+PyTrilinos [PyTrilinos]_, which can be used (assuming is installed) by
+starting the engines with::
+
+    	mpirun -n 4 ipengine --mpi=pytrilinos
+
+Automatic starting using PBS and :command:`ipcluster`
+-----------------------------------------------------
+
+The :command:`ipcluster` command also has built-in integration with PBS. For more information on this approach, see our documentation on :ref:`ipcluster <parallel_process>`.
+
+Actually using MPI
+==================
+
+Once the engines are running with MPI enabled, you are ready to go.  You can now call any code that uses MPI in the IPython engines.  And, all of this can be done interactively.  Here we show a simple example that uses mpi4py [mpi4py]_.
+
+First, lets define a simply function that uses MPI to calculate the sum of a distributed array.  Save the following text in a file called :file:`psum.py`:
+
+.. sourcecode:: python
+
+    from mpi4py import MPI
+    import numpy as np
+    
+    def psum(a):
+        s = np.sum(a)
+        return MPI.COMM_WORLD.Allreduce(s,MPI.SUM)
+
+Now, start an IPython cluster in the same directory as :file:`psum.py`::
+
+    $ ipcluster mpirun -n 4
+
+Finally, connect to the cluster and use this function interactively.  In this case, we create a random array on each engine and sum up all the random arrays using our :func:`psum` function:
+
+.. sourcecode:: ipython
+
+    In [1]: from IPython.kernel import client
+    
+    In [2]: mec = client.MultiEngineClient()
+    
+    In [3]: mec.activate()
+    
+    In [4]: px import numpy as np
+    Parallel execution on engines: all
+    Out[4]: 
+    <Results List>
+    [0] In [13]: import numpy as np
+    [1] In [13]: import numpy as np
+    [2] In [13]: import numpy as np
+    [3] In [13]: import numpy as np
+    
+    In [6]: px a = np.random.rand(100)
+    Parallel execution on engines: all
+    Out[6]: 
+    <Results List>
+    [0] In [15]: a = np.random.rand(100)
+    [1] In [15]: a = np.random.rand(100)
+    [2] In [15]: a = np.random.rand(100)
+    [3] In [15]: a = np.random.rand(100)
+    
+    In [7]: px from psum import psum
+    Parallel execution on engines: all
+    Out[7]: 
+    <Results List>
+    [0] In [16]: from psum import psum
+    [1] In [16]: from psum import psum
+    [2] In [16]: from psum import psum
+    [3] In [16]: from psum import psum
+    
+    In [8]: px s = psum(a)
+    Parallel execution on engines: all
+    Out[8]: 
+    <Results List>
+    [0] In [17]: s = psum(a)
+    [1] In [17]: s = psum(a)
+    [2] In [17]: s = psum(a)
+    [3] In [17]: s = psum(a)
+    
+    In [9]: px print s
+    Parallel execution on engines: all
+    Out[9]: 
+    <Results List>
+    [0] In [18]: print s
+    [0] Out[18]: 187.451545803
+    
+    [1] In [18]: print s
+    [1] Out[18]: 187.451545803
+    
+    [2] In [18]: print s
+    [2] Out[18]: 187.451545803
+
+    [3] In [18]: print s
+    [3] Out[18]: 187.451545803
+
+Any Python code that makes calls to MPI can be used in this manner, including
+compiled C, C++ and Fortran libraries that have been exposed to Python.
+
+.. [MPI] Message Passing Interface.  http://www-unix.mcs.anl.gov/mpi/
+.. [mpi4py] MPI for Python. mpi4py: http://mpi4py.scipy.org/
+.. [OpenMPI] Open MPI. http://www.open-mpi.org/
+.. [PyTrilinos] PyTrilinos. http://trilinos.sandia.gov/packages/pytrilinos/
  No newline at end of file

docs/source/parallel/parallel_multiengine.txt

@@ -1,728 +1,828
 .. _parallelmultiengine:
 
-=================================
-IPython's MultiEngine interface
-=================================
-
-.. contents::
-
-The MultiEngine interface represents one possible way of working with a
-set of IPython engines. The basic idea behind the MultiEngine interface is
-that the capabilities of each engine are explicitly exposed to the user.
-Thus, in the MultiEngine interface, each engine is given an id that is
-used to identify the engine and give it work to do. This interface is very
-intuitive and is designed with interactive usage in mind, and is thus the
-best place for new users of IPython to begin.
+===============================
+IPython's multiengine interface
+===============================
+
+The multiengine interface represents one possible way of working with a set of
+IPython engines. The basic idea behind the multiengine interface is that the
+capabilities of each engine are directly and explicitly exposed to the user.
+Thus, in the multiengine interface, each engine is given an id that is used to
+identify the engine and give it work to do. This interface is very intuitive
+and is designed with interactive usage in mind, and is thus the best place for
+new users of IPython to begin.
 
 Starting the IPython controller and engines
 ===========================================
 
 To follow along with this tutorial, you will need to start the IPython
-controller and four IPython engines. The simplest way of doing this is to
-use the ``ipcluster`` command::
+controller and four IPython engines. The simplest way of doing this is to use
+the :command:`ipcluster` command::
 
-	$ ipcluster -n 4
+	$ ipcluster local -n 4
 	
-For more detailed information about starting the controller and engines, see our :ref:`introduction <ip1par>` to using IPython for parallel computing.
+For more detailed information about starting the controller and engines, see
+our :ref:`introduction <ip1par>` to using IPython for parallel computing.
 
 Creating a ``MultiEngineClient`` instance
 =========================================
 
-The first step is to import the IPython ``client`` module and then create a ``MultiEngineClient`` instance::
+The first step is to import the IPython :mod:`IPython.kernel.client` module
+and then create a :class:`MultiEngineClient` instance:
+
+.. sourcecode:: ipython
 
 	In [1]: from IPython.kernel import client
 	
 	In [2]: mec = client.MultiEngineClient()
 
-To make sure there are engines connected to the controller, use can get a list of engine ids::
+This form assumes that the :file:`ipcontroller-mec.furl` is in the
+:file:`~./ipython/security` directory on the client's host. If not, the
+location of the FURL file must be given as an argument to the
+constructor:
+
+.. sourcecode:: ipython
+
+    In [2]: mec = client.MultiEngineClient('/path/to/my/ipcontroller-mec.furl')
+
+To make sure there are engines connected to the controller, use can get a list
+of engine ids:
+
+.. sourcecode:: ipython
 
 	In [3]: mec.get_ids()
 	Out[3]: [0, 1, 2, 3]
 
 Here we see that there are four engines ready to do work for us.
 
+Quick and easy parallelism
+==========================
+
+In many cases, you simply want to apply a Python function to a sequence of objects, but *in parallel*.  The multiengine interface provides two simple ways of accomplishing this:  a parallel version of :func:`map` and ``@parallel`` function decorator.
+
+Parallel map
+------------
+
+Python's builtin :func:`map` functions allows a function to be applied to a
+sequence element-by-element. This type of code is typically trivial to
+parallelize. In fact, the multiengine interface in IPython already has a
+parallel version of :meth:`map` that works just like its serial counterpart:
+
+.. sourcecode:: ipython
+
+	In [63]: serial_result = map(lambda x:x**10, range(32))
+
+	In [64]: parallel_result = mec.map(lambda x:x**10, range(32))
+
+	In [65]: serial_result==parallel_result
+	Out[65]: True
+
+.. note::
+
+    The multiengine interface version of :meth:`map` does not do any load
+    balancing.  For a load balanced version, see the task interface.
+
+.. seealso::
+
+    The :meth:`map` method has a number of options that can be controlled by
+    the :meth:`mapper` method.  See its docstring for more information.
+
+Parallel function decorator
+---------------------------
+
+Parallel functions are just like normal function, but they can be called on sequences and *in parallel*.  The multiengine interface provides a decorator that turns any Python function into a parallel function:
+
+.. sourcecode:: ipython
+
+    In [10]: @mec.parallel()
+       ....: def f(x):
+       ....:     return 10.0*x**4
+       ....: 
+
+    In [11]: f(range(32))    # this is done in parallel
+    Out[11]: 
+    [0.0,10.0,160.0,...]
+
+See the docstring for the :meth:`parallel` decorator for options.
+
 Running Python commands
 =======================
 
-The most basic type of operation that can be performed on the engines is to execute Python code. Executing Python code can be done in blocking or non-blocking mode (blocking is default) using the ``execute`` method.
+The most basic type of operation that can be performed on the engines is to
+execute Python code. Executing Python code can be done in blocking or
+non-blocking mode (blocking is default) using the :meth:`execute` method.
 
 Blocking execution
 ------------------
 
-In blocking mode, the ``MultiEngineClient`` object (called ``mec`` in
+In blocking mode, the :class:`MultiEngineClient` object (called ``mec`` in
 these examples) submits the command to the controller, which places the
-command in the engines' queues for execution. The ``execute`` call then
-blocks until the engines are done executing the command::
+command in the engines' queues for execution. The :meth:`execute` call then
+blocks until the engines are done executing the command:
+
+.. sourcecode:: ipython
 
 	# The default is to run on all engines
 	In [4]: mec.execute('a=5')
 	Out[4]: 
 	<Results List>
 	[0] In [1]: a=5
 	[1] In [1]: a=5
 	[2] In [1]: a=5
 	[3] In [1]: a=5
 
 	In [5]: mec.execute('b=10')
 	Out[5]: 
 	<Results List>
 	[0] In [2]: b=10
 	[1] In [2]: b=10
 	[2] In [2]: b=10
 	[3] In [2]: b=10
 
-Python commands can be executed on specific engines by calling execute using the ``targets`` keyword argument::
+Python commands can be executed on specific engines by calling execute using
+the ``targets`` keyword argument:
+
+.. sourcecode:: ipython
 
 	In [6]: mec.execute('c=a+b',targets=[0,2])
 	Out[6]: 
 	<Results List>
 	[0] In [3]: c=a+b
 	[2] In [3]: c=a+b
 
 
 	In [7]: mec.execute('c=a-b',targets=[1,3])
 	Out[7]: 
 	<Results List>
 	[1] In [3]: c=a-b
 	[3] In [3]: c=a-b
 
 
 	In [8]: mec.execute('print c')
 	Out[8]: 
 	<Results List>
 	[0] In [4]: print c
 	[0] Out[4]: 15
 
 	[1] In [4]: print c
 	[1] Out[4]: -5
 
 	[2] In [4]: print c
 	[2] Out[4]: 15
 
 	[3] In [4]: print c
 	[3] Out[4]: -5
 
-This example also shows one of the most important things about the IPython engines: they have a persistent user namespaces.  The ``execute`` method returns a Python ``dict`` that contains useful information::
+This example also shows one of the most important things about the IPython
+engines: they have a persistent user namespaces. The :meth:`execute` method
+returns a Python ``dict`` that contains useful information:
+
+.. sourcecode:: ipython
 
 	In [9]: result_dict = mec.execute('d=10; print d')
 
 	In [10]: for r in result_dict:
 	   ....:     print r
 	   ....:     
 	   ....:     
 	{'input': {'translated': 'd=10; print d', 'raw': 'd=10; print d'}, 'number': 5, 'id': 0, 'stdout': '10\n'}
 	{'input': {'translated': 'd=10; print d', 'raw': 'd=10; print d'}, 'number': 5, 'id': 1, 'stdout': '10\n'}
 	{'input': {'translated': 'd=10; print d', 'raw': 'd=10; print d'}, 'number': 5, 'id': 2, 'stdout': '10\n'}
 	{'input': {'translated': 'd=10; print d', 'raw': 'd=10; print d'}, 'number': 5, 'id': 3, 'stdout': '10\n'}
 
 Non-blocking execution
 ----------------------
 
-In non-blocking mode, ``execute`` submits the command to be executed and then returns a
-``PendingResult`` object immediately. The ``PendingResult`` object gives you a way of getting a
-result at a later time through its ``get_result`` method or ``r`` attribute. This allows you to
-quickly submit long running commands without blocking your local Python/IPython session::
+In non-blocking mode, :meth:`execute` submits the command to be executed and
+then returns a :class:`PendingResult` object immediately. The
+:class:`PendingResult` object gives you a way of getting a result at a later
+time through its :meth:`get_result` method or :attr:`r` attribute. This allows
+you to quickly submit long running commands without blocking your local
+Python/IPython session:
+
+.. sourcecode:: ipython
 
 	# In blocking mode
 	In [6]: mec.execute('import time')
 	Out[6]:
 	<Results List>
 	[0] In [1]: import time
 	[1] In [1]: import time
 	[2] In [1]: import time
 	[3] In [1]: import time
 
 	# In non-blocking mode
 	In [7]: pr = mec.execute('time.sleep(10)',block=False)
 
 	# Now block for the result
 	In [8]: pr.get_result()
 	Out[8]:
 	<Results List>
 	[0] In [2]: time.sleep(10)
 	[1] In [2]: time.sleep(10)
 	[2] In [2]: time.sleep(10)
 	[3] In [2]: time.sleep(10)
 
 	# Again in non-blocking mode
 	In [9]: pr = mec.execute('time.sleep(10)',block=False)
 
 	# Poll to see if the result is ready
 	In [10]: pr.get_result(block=False)
 
 	# A shorthand for get_result(block=True)
 	In [11]: pr.r
 	Out[11]:
 	<Results List>
 	[0] In [3]: time.sleep(10)
 	[1] In [3]: time.sleep(10)
 	[2] In [3]: time.sleep(10)
 	[3] In [3]: time.sleep(10)
 
-Often, it is desirable to wait until a set of ``PendingResult`` objects are done.  For this, there is a the method ``barrier``.  This method takes a tuple of ``PendingResult`` objects and blocks until all of the associated results are ready::
+Often, it is desirable to wait until a set of :class:`PendingResult` objects
+are done. For this, there is a the method :meth:`barrier`. This method takes a
+tuple of :class:`PendingResult` objects and blocks until all of the associated
+results are ready:
+
+.. sourcecode:: ipython
 
 	In [72]: mec.block=False
 
 	# A trivial list of PendingResults objects
 	In [73]: pr_list = [mec.execute('time.sleep(3)') for i in range(10)]
 
 	# Wait until all of them are done
 	In [74]: mec.barrier(pr_list)
 
 	# Then, their results are ready using get_result or the r attribute
 	In [75]: pr_list[0].r
 	Out[75]: 
 	<Results List>
 	[0] In [20]: time.sleep(3)
 	[1] In [19]: time.sleep(3)
 	[2] In [20]: time.sleep(3)
 	[3] In [19]: time.sleep(3)
 
 
 The ``block`` and ``targets`` keyword arguments and attributes
 --------------------------------------------------------------
 
-Most commands in the multiengine interface (like ``execute``) accept ``block`` and ``targets``
-as keyword arguments. As we have seen above, these keyword arguments control the blocking mode
-and which engines the command is applied to. The ``MultiEngineClient`` class also has ``block``
-and ``targets`` attributes that control the default behavior when the keyword arguments are not
-provided. Thus the following logic is used for ``block`` and ``targets``:
+Most methods in the multiengine interface (like :meth:`execute`) accept
+``block`` and ``targets`` as keyword arguments. As we have seen above, these
+keyword arguments control the blocking mode and which engines the command is
+applied to. The :class:`MultiEngineClient` class also has :attr:`block` and
+:attr:`targets` attributes that control the default behavior when the keyword
+arguments are not provided. Thus the following logic is used for :attr:`block`
+and :attr:`targets`:
+
+* If no keyword argument is provided, the instance attributes are used.
+* Keyword argument, if provided override the instance attributes.
 
-	* If no keyword argument is provided, the instance attributes are used.
-	* Keyword argument, if provided override the instance attributes.
+The following examples demonstrate how to use the instance attributes:
 
-The following examples demonstrate how to use the instance attributes::
+.. sourcecode:: ipython
 
 	In [16]: mec.targets = [0,2]
 
 	In [17]: mec.block = False
 
 	In [18]: pr = mec.execute('a=5')
 
 	In [19]: pr.r
 	Out[19]: 
 	<Results List>
 	[0] In [6]: a=5
 	[2] In [6]: a=5
 
 	# Note targets='all' means all engines
 	In [20]: mec.targets = 'all'
 
 	In [21]: mec.block = True
 
 	In [22]: mec.execute('b=10; print b')
 	Out[22]: 
 	<Results List>
 	[0] In [7]: b=10; print b
 	[0] Out[7]: 10
 
 	[1] In [6]: b=10; print b
 	[1] Out[6]: 10
 
 	[2] In [7]: b=10; print b
 	[2] Out[7]: 10
 
 	[3] In [6]: b=10; print b
 	[3] Out[6]: 10
 
-The ``block`` and ``targets`` instance attributes also determine the behavior of the parallel
-magic commands...
+The :attr:`block` and :attr:`targets` instance attributes also determine the
+behavior of the parallel magic commands.
 
 
 Parallel magic commands
 -----------------------
 
-We provide a few IPython magic commands (``%px``, ``%autopx`` and ``%result``) that make it more pleasant to execute Python commands on the engines interactively. These are simply shortcuts to ``execute`` and ``get_result``. The ``%px`` magic executes a single Python command on the engines specified by the `magicTargets``targets` attribute of the ``MultiEngineClient`` instance (by default this is 'all')::
+We provide a few IPython magic commands (``%px``, ``%autopx`` and ``%result``)
+that make it more pleasant to execute Python commands on the engines
+interactively. These are simply shortcuts to :meth:`execute` and
+:meth:`get_result`. The ``%px`` magic executes a single Python command on the
+engines specified by the :attr:`targets` attribute of the
+:class:`MultiEngineClient` instance (by default this is ``'all'``):
+
+.. sourcecode:: ipython
 
 	# Make this MultiEngineClient active for parallel magic commands
 	In [23]: mec.activate()
 
 	In [24]: mec.block=True
 
 	In [25]: import numpy
 
 	In [26]: %px import numpy
 	Executing command on Controller
 	Out[26]:
 	<Results List>
 	[0] In [8]: import numpy
 	[1] In [7]: import numpy
 	[2] In [8]: import numpy
 	[3] In [7]: import numpy
 
 
 	In [27]: %px a = numpy.random.rand(2,2)
 	Executing command on Controller
 	Out[27]:
 	<Results List>
 	[0] In [9]: a = numpy.random.rand(2,2)
 	[1] In [8]: a = numpy.random.rand(2,2)
 	[2] In [9]: a = numpy.random.rand(2,2)
 	[3] In [8]: a = numpy.random.rand(2,2)
 
 
 	In [28]: %px print numpy.linalg.eigvals(a)
 	Executing command on Controller
 	Out[28]:
 	<Results List>
 	[0] In [10]: print numpy.linalg.eigvals(a)
 	[0] Out[10]: [ 1.28167017  0.14197338]
 
 	[1] In [9]: print numpy.linalg.eigvals(a)
 	[1] Out[9]: [-0.14093616  1.27877273]
 
 	[2] In [10]: print numpy.linalg.eigvals(a)
 	[2] Out[10]: [-0.37023573  1.06779409]
 
 	[3] In [9]: print numpy.linalg.eigvals(a)
 	[3] Out[9]: [ 0.83664764 -0.25602658]
 
-The ``%result`` magic gets and prints the stdin/stdout/stderr of the last command executed on each engine.  It is simply a shortcut to the ``get_result`` method::
+The ``%result`` magic gets and prints the stdin/stdout/stderr of the last
+command executed on each engine. It is simply a shortcut to the
+:meth:`get_result` method:
+
+.. sourcecode:: ipython
 
 	In [29]: %result
 	Out[29]:
 	<Results List>
 	[0] In [10]: print numpy.linalg.eigvals(a)
 	[0] Out[10]: [ 1.28167017  0.14197338]
 
 	[1] In [9]: print numpy.linalg.eigvals(a)
 	[1] Out[9]: [-0.14093616  1.27877273]
 
 	[2] In [10]: print numpy.linalg.eigvals(a)
 	[2] Out[10]: [-0.37023573  1.06779409]
 
 	[3] In [9]: print numpy.linalg.eigvals(a)
 	[3] Out[9]: [ 0.83664764 -0.25602658]
 
-The ``%autopx`` magic switches to a mode where everything you type is executed on the engines given by the ``targets`` attribute::
+The ``%autopx`` magic switches to a mode where everything you type is executed
+on the engines given by the :attr:`targets` attribute:
+
+.. sourcecode:: ipython
 
 	In [30]: mec.block=False
 
 	In [31]: %autopx
 	Auto Parallel Enabled
 	Type %autopx to disable
 
 	In [32]: max_evals = []
 	<IPython.kernel.multiengineclient.PendingResult object at 0x17b8a70>
 
 	In [33]: for i in range(100):
 	   ....:     a = numpy.random.rand(10,10)
 	   ....:     a = a+a.transpose()
 	   ....:     evals = numpy.linalg.eigvals(a)
 	   ....:     max_evals.append(evals[0].real)
 	   ....:
 	   ....:
 	<IPython.kernel.multiengineclient.PendingResult object at 0x17af8f0>
 
 	In [34]: %autopx
 	Auto Parallel Disabled
 
 	In [35]: mec.block=True
 
 	In [36]: px print "Average max eigenvalue is: ", sum(max_evals)/len(max_evals)
 	Executing command on Controller
 	Out[36]:
 	<Results List>
 	[0] In [13]: print "Average max eigenvalue is: ", sum(max_evals)/len(max_evals)
 	[0] Out[13]: Average max eigenvalue is:  10.1387247332
 
 	[1] In [12]: print "Average max eigenvalue is: ", sum(max_evals)/len(max_evals)
 	[1] Out[12]: Average max eigenvalue is:  10.2076902286
 
 	[2] In [13]: print "Average max eigenvalue is: ", sum(max_evals)/len(max_evals)
 	[2] Out[13]: Average max eigenvalue is:  10.1891484655
 
 	[3] In [12]: print "Average max eigenvalue is: ", sum(max_evals)/len(max_evals)
 	[3] Out[12]: Average max eigenvalue is:  10.1158837784
 
-Using the ``with`` statement of Python 2.5
-------------------------------------------
-
-Python 2.5 introduced the ``with`` statement.  The ``MultiEngineClient`` can be used with the ``with`` statement to execute a block of code on the engines indicated by the ``targets`` attribute::
-
-	In [3]: with mec:
-	   ...:     client.remote()    # Required so the following code is not run locally
-	   ...:     a = 10
-	   ...:     b = 30
-	   ...:     c = a+b
-	   ...:     
-	   ...:     
-
-	In [4]: mec.get_result()
-	Out[4]: 
-	<Results List>
-	[0] In [1]: a = 10
-	b = 30
-	c = a+b
-
-	[1] In [1]: a = 10
-	b = 30
-	c = a+b
-
-	[2] In [1]: a = 10
-	b = 30
-	c = a+b
 
-	[3] In [1]: a = 10
-	b = 30
-	c = a+b
+Moving Python objects around
+============================
 
-This is basically another way of calling execute, but one with allows you to avoid writing code in strings.  When used in this way, the attributes ``targets`` and ``block`` are used to control how the code is executed.  For now, if you run code in non-blocking mode you won't have access to the ``PendingResult``.
-
-Moving Python object around
-===========================
-
-In addition to executing code on engines, you can transfer Python objects to and from your
-IPython session and the engines. In IPython, these operations are called ``push`` (sending an
-object to the engines) and ``pull`` (getting an object from the engines).
+In addition to executing code on engines, you can transfer Python objects to
+and from your IPython session and the engines. In IPython, these operations
+are called :meth:`push` (sending an object to the engines) and :meth:`pull`
+(getting an object from the engines).
 
 Basic push and pull
 -------------------
 
-Here are some examples of how you use ``push`` and ``pull``::
+Here are some examples of how you use :meth:`push` and :meth:`pull`:
+
+.. sourcecode:: ipython
 
 	In [38]: mec.push(dict(a=1.03234,b=3453))
 	Out[38]: [None, None, None, None]
 
 	In [39]: mec.pull('a')
 	Out[39]: [1.03234, 1.03234, 1.03234, 1.03234]
 
 	In [40]: mec.pull('b',targets=0)
 	Out[40]: [3453]
 
 	In [41]: mec.pull(('a','b'))
 	Out[41]: [[1.03234, 3453], [1.03234, 3453], [1.03234, 3453], [1.03234, 3453]]
 
 	In [42]: mec.zip_pull(('a','b'))
 	Out[42]: [(1.03234, 1.03234, 1.03234, 1.03234), (3453, 3453, 3453, 3453)]
 
 	In [43]: mec.push(dict(c='speed'))
 	Out[43]: [None, None, None, None]
 
 	In [44]: %px print c
 	Executing command on Controller
 	Out[44]: 
 	<Results List>
 	[0] In [14]: print c
 	[0] Out[14]: speed
 
 	[1] In [13]: print c
 	[1] Out[13]: speed
 
 	[2] In [14]: print c
 	[2] Out[14]: speed
 
 	[3] In [13]: print c
 	[3] Out[13]: speed
 
-In non-blocking mode ``push`` and ``pull`` also return ``PendingResult`` objects::
+In non-blocking mode :meth:`push` and :meth:`pull` also return
+:class:`PendingResult` objects:
+
+.. sourcecode:: ipython
 
 	In [47]: mec.block=False
 
 	In [48]: pr = mec.pull('a')
 
 	In [49]: pr.r
 	Out[49]: [1.03234, 1.03234, 1.03234, 1.03234]
 
 
 Push and pull for functions
 ---------------------------
 
-Functions can also be pushed and pulled using ``push_function`` and ``pull_function``::
+Functions can also be pushed and pulled using :meth:`push_function` and
+:meth:`pull_function`:
+
+.. sourcecode:: ipython
+
+    In [52]: mec.block=True
 
 	In [53]: def f(x):
 	   ....:     return 2.0*x**4
 	   ....: 
 
 	In [54]: mec.push_function(dict(f=f))
 	Out[54]: [None, None, None, None]
 
 	In [55]: mec.execute('y = f(4.0)')
 	Out[55]: 
 	<Results List>
 	[0] In [15]: y = f(4.0)
 	[1] In [14]: y = f(4.0)
 	[2] In [15]: y = f(4.0)
 	[3] In [14]: y = f(4.0)
 
 
 	In [56]: px print y
 	Executing command on Controller
 	Out[56]: 
 	<Results List>
 	[0] In [16]: print y
 	[0] Out[16]: 512.0
 
 	[1] In [15]: print y
 	[1] Out[15]: 512.0
 
 	[2] In [16]: print y
 	[2] Out[16]: 512.0
 
 	[3] In [15]: print y
 	[3] Out[15]: 512.0
 
 
 Dictionary interface
 --------------------
 
-As a shorthand to ``push`` and ``pull``, the ``MultiEngineClient`` class implements some of the Python dictionary interface. This make the remote namespaces of the engines appear as a local dictionary. Underneath, this uses ``push`` and ``pull``::
+As a shorthand to :meth:`push` and :meth:`pull`, the
+:class:`MultiEngineClient` class implements some of the Python dictionary
+interface. This make the remote namespaces of the engines appear as a local
+dictionary. Underneath, this uses :meth:`push` and :meth:`pull`:
+
+.. sourcecode:: ipython
 
 	In [50]: mec.block=True
 
 	In [51]: mec['a']=['foo','bar']
 
 	In [52]: mec['a']
 	Out[52]: [['foo', 'bar'], ['foo', 'bar'], ['foo', 'bar'], ['foo', 'bar']]
 
 Scatter and gather
 ------------------
 
-Sometimes it is useful to partition a sequence and push the partitions to different engines. In
-MPI language, this is know as scatter/gather and we follow that terminology. However, it is
-important to remember that in IPython ``scatter`` is from the interactive IPython session to
-the engines and ``gather`` is from the engines back to the interactive IPython session. For
-scatter/gather operations between engines, MPI should be used::
+Sometimes it is useful to partition a sequence and push the partitions to
+different engines. In MPI language, this is know as scatter/gather and we
+follow that terminology. However, it is important to remember that in
+IPython's :class:`MultiEngineClient` class, :meth:`scatter` is from the
+interactive IPython session to the engines and :meth:`gather` is from the
+engines back to the interactive IPython session. For scatter/gather operations
+between engines, MPI should be used:
+
+.. sourcecode:: ipython
 
 	In [58]: mec.scatter('a',range(16))
 	Out[58]: [None, None, None, None]
 
 	In [59]: px print a
 	Executing command on Controller
 	Out[59]: 
 	<Results List>
 	[0] In [17]: print a
 	[0] Out[17]: [0, 1, 2, 3]
 
 	[1] In [16]: print a
 	[1] Out[16]: [4, 5, 6, 7]
 
 	[2] In [17]: print a
 	[2] Out[17]: [8, 9, 10, 11]
 
 	[3] In [16]: print a
 	[3] Out[16]: [12, 13, 14, 15]
 
 
 	In [60]: mec.gather('a')
 	Out[60]: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
 
 Other things to look at
 =======================
 
-Parallel map
-------------
-
-Python's builtin ``map`` functions allows a function to be applied to a sequence element-by-element.  This type of code is typically trivial to parallelize.  In fact, the MultiEngine interface in IPython already has a parallel version of ``map`` that works just like its serial counterpart::
-
-	In [63]: serial_result = map(lambda x:x**10, range(32))
-
-	In [64]: parallel_result = mec.map(lambda x:x**10, range(32))
-
-	In [65]: serial_result==parallel_result
-	Out[65]: True
-
-As you would expect, the parallel version of ``map`` is also influenced by the ``block`` and ``targets`` keyword arguments and attributes.
-
 How to do parallel list comprehensions
 --------------------------------------
 
-In many cases list comprehensions are nicer than using the map function.  While we don't have fully parallel list comprehensions, it is simple to get the basic effect using ``scatter`` and ``gather``::
+In many cases list comprehensions are nicer than using the map function. While
+we don't have fully parallel list comprehensions, it is simple to get the
+basic effect using :meth:`scatter` and :meth:`gather`:
+
+.. sourcecode:: ipython
 
 	In [66]: mec.scatter('x',range(64))
 	Out[66]: [None, None, None, None]
 
 	In [67]: px y = [i**10 for i in x]
 	Executing command on Controller
 	Out[67]: 
 	<Results List>
 	[0] In [19]: y = [i**10 for i in x]
 	[1] In [18]: y = [i**10 for i in x]
 	[2] In [19]: y = [i**10 for i in x]
 	[3] In [18]: y = [i**10 for i in x]
 
 
 	In [68]: y = mec.gather('y')
 
 	In [69]: print y
 	[0, 1, 1024, 59049, 1048576, 9765625, 60466176, 282475249, 1073741824,...]
 
-Parallel Exceptions
+Parallel exceptions
 -------------------
 
-In the MultiEngine interface, parallel commands can raise Python exceptions, just like serial commands.  But, it is a little subtle, because a single parallel command can actually raise multiple exceptions (one for each engine the command was run on).  To express this idea, the MultiEngine interface has a ``CompositeError`` exception class that will be raised in most cases.  The ``CompositeError`` class is a special type of exception that wraps one or more other types of exceptions.  Here is how it works::
+In the multiengine interface, parallel commands can raise Python exceptions,
+just like serial commands. But, it is a little subtle, because a single
+parallel command can actually raise multiple exceptions (one for each engine
+the command was run on). To express this idea, the MultiEngine interface has a
+:exc:`CompositeError` exception class that will be raised in most cases. The
+:exc:`CompositeError` class is a special type of exception that wraps one or
+more other types of exceptions. Here is how it works:
+
+.. sourcecode:: ipython
 
 	In [76]: mec.block=True
 
 	In [77]: mec.execute('1/0')
 	---------------------------------------------------------------------------
 	CompositeError                            Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
 	/ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in execute(self, lines, targets, block)
 	    432         targets, block = self._findTargetsAndBlock(targets, block)
 	    433         result = blockingCallFromThread(self.smultiengine.execute, lines,
 	--> 434             targets=targets, block=block)
 	    435         if block:
 	    436             result = ResultList(result)
 
 	/ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
 	     72             result.raiseException()
 	     73         except Exception, e:
 	---> 74             raise e
 	     75     return result
 	     76 
 
 	CompositeError: one or more exceptions from call to method: execute
 	[0:execute]: ZeroDivisionError: integer division or modulo by zero
 	[1:execute]: ZeroDivisionError: integer division or modulo by zero
 	[2:execute]: ZeroDivisionError: integer division or modulo by zero
 	[3:execute]: ZeroDivisionError: integer division or modulo by zero
 
-Notice how the error message printed when ``CompositeError`` is raised has information about the individual exceptions that were raised on each engine.  If you want, you can even raise one of these original exceptions::
+Notice how the error message printed when :exc:`CompositeError` is raised has information about the individual exceptions that were raised on each engine.  If you want, you can even raise one of these original exceptions:
+
+.. sourcecode:: ipython
 
 	In [80]: try:
 	   ....:     mec.execute('1/0')
 	   ....: except client.CompositeError, e:
 	   ....:     e.raise_exception()
 	   ....:     
 	   ....:     
 	---------------------------------------------------------------------------
 	ZeroDivisionError                         Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
 	/ipython1-client-r3021/ipython1/kernel/error.pyc in raise_exception(self, excid)
 	    156             raise IndexError("an exception with index %i does not exist"%excid)
 	    157         else:
 	--> 158             raise et, ev, etb
 	    159 
 	    160 def collect_exceptions(rlist, method):
 
 	ZeroDivisionError: integer division or modulo by zero
 
-If you are working in IPython, you can simple type ``%debug`` after one of these ``CompositeError`` is raised, and inspect the exception instance::
+If you are working in IPython, you can simple type ``%debug`` after one of
+these :exc:`CompositeError` exceptions is raised, and inspect the exception
+instance:
+
+.. sourcecode:: ipython
 
 	In [81]: mec.execute('1/0')
 	---------------------------------------------------------------------------
 	CompositeError                            Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
 	/ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in execute(self, lines, targets, block)
 	    432         targets, block = self._findTargetsAndBlock(targets, block)
 	    433         result = blockingCallFromThread(self.smultiengine.execute, lines,
 	--> 434             targets=targets, block=block)
 	    435         if block:
 	    436             result = ResultList(result)
 
 	/ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
 	     72             result.raiseException()
 	     73         except Exception, e:
 	---> 74             raise e
 	     75     return result
 	     76 
 
 	CompositeError: one or more exceptions from call to method: execute
 	[0:execute]: ZeroDivisionError: integer division or modulo by zero
 	[1:execute]: ZeroDivisionError: integer division or modulo by zero
 	[2:execute]: ZeroDivisionError: integer division or modulo by zero
 	[3:execute]: ZeroDivisionError: integer division or modulo by zero
 
 	In [82]: %debug
 	> 
 	
 	/ipython1-client-r3021/ipython1/kernel/twistedutil.py(74)blockingCallFromThread()
 	     73         except Exception, e:
 	---> 74             raise e
 	     75     return result
 
 	# With the debugger running, e is the exceptions instance.  We can tab complete
 	# on it and see the extra methods that are available.
 	ipdb> e.
 	e.__class__         e.__getitem__       e.__new__           e.__setstate__      e.args
 	e.__delattr__       e.__getslice__      e.__reduce__        e.__str__           e.elist
 	e.__dict__          e.__hash__          e.__reduce_ex__     e.__weakref__       e.message
 	e.__doc__           e.__init__          e.__repr__          e._get_engine_str   e.print_tracebacks
 	e.__getattribute__  e.__module__        e.__setattr__       e._get_traceback    e.raise_exception
 	ipdb> e.print_tracebacks()
 	[0:execute]: 
 	---------------------------------------------------------------------------
 	ZeroDivisionError                         Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<string> in <module>()
 
 	ZeroDivisionError: integer division or modulo by zero
 
 	[1:execute]: 
 	---------------------------------------------------------------------------
 	ZeroDivisionError                         Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<string> in <module>()
 
 	ZeroDivisionError: integer division or modulo by zero
 
 	[2:execute]: 
 	---------------------------------------------------------------------------
 	ZeroDivisionError                         Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<string> in <module>()
 
 	ZeroDivisionError: integer division or modulo by zero
 
 	[3:execute]: 
 	---------------------------------------------------------------------------
 	ZeroDivisionError                         Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<string> in <module>()
 
 	ZeroDivisionError: integer division or modulo by zero
 
-All of this same error handling magic even works in non-blocking mode::
+.. note::
+
+    The above example appears to be broken right now because of a change in 
+    how we are using Twisted.
+
+All of this same error handling magic even works in non-blocking mode:
+
+.. sourcecode:: ipython
 
 	In [83]: mec.block=False
 
 	In [84]: pr = mec.execute('1/0')
 
 	In [85]: pr.r
 	---------------------------------------------------------------------------
 	CompositeError                            Traceback (most recent call last)
 
 	/ipython1-client-r3021/docs/examples/<ipython console> in <module>()
 
 	/ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in _get_r(self)
 	    170 
 	    171     def _get_r(self):
 	--> 172         return self.get_result(block=True)
 	    173 
 	    174     r = property(_get_r)
 
 	/ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in get_result(self, default, block)
 	    131                 return self.result
 	    132         try:
 	--> 133             result = self.client.get_pending_deferred(self.result_id, block)
 	    134         except error.ResultNotCompleted:
 	    135             return default
 
 	/ipython1-client-r3021/ipython1/kernel/multiengineclient.pyc in get_pending_deferred(self, deferredID, block)
 	    385 
 	    386     def get_pending_deferred(self, deferredID, block):
 	--> 387         return blockingCallFromThread(self.smultiengine.get_pending_deferred, deferredID, block)
 	    388 
 	    389     def barrier(self, pendingResults):
 
 	/ipython1-client-r3021/ipython1/kernel/twistedutil.pyc in blockingCallFromThread(f, *a, **kw)
 	     72             result.raiseException()
 	     73         except Exception, e:
 	---> 74             raise e
 	     75     return result
 	     76 
 
 	CompositeError: one or more exceptions from call to method: execute
 	[0:execute]: ZeroDivisionError: integer division or modulo by zero
 	[1:execute]: ZeroDivisionError: integer division or modulo by zero
 	[2:execute]: ZeroDivisionError: integer division or modulo by zero
 	[3:execute]: ZeroDivisionError: integer division or modulo by zero
 
 

docs/source/parallel/parallel_task.txt

@@ -1,240 +1,99
 .. _paralleltask:
 
-=================================
-The IPython Task interface
-=================================
+==========================
+The IPython task interface
+==========================
 
-.. contents::
+The task interface to the controller presents the engines as a fault tolerant, dynamic load-balanced system or workers. Unlike the multiengine interface, in the task interface, the user have no direct access to individual engines. In some ways, this interface is simpler, but in other ways it is more powerful.
 
-The ``Task`` interface to the controller presents the engines as a fault tolerant, dynamic load-balanced system or workers. Unlike the ``MultiEngine`` interface, in the ``Task`` interface, the user have no direct access to individual engines. In some ways, this interface is simpler, but in other ways it is more powerful. Best of all the user can use both of these interfaces at the same time to take advantage or both of their strengths.  When the user can break up the user's work into segments that do not depend on previous execution, the ``Task`` interface is ideal.  But it also has more power and flexibility, allowing the user to guide the distribution of jobs, without having to assign Tasks to engines explicitly.
+Best of all the user can use both of these interfaces running at the same time to take advantage or both of their strengths.  When the user can break up the user's work into segments that do not depend on previous execution, the task interface is ideal.  But it also has more power and flexibility, allowing the user to guide the distribution of jobs, without having to assign tasks to engines explicitly.
 
 Starting the IPython controller and engines
 ===========================================
 
-To follow along with this tutorial, the user will need to start the IPython
-controller and four IPython engines. The simplest way of doing this is to
-use the ``ipcluster`` command::
+To follow along with this tutorial, you will need to start the IPython
+controller and four IPython engines. The simplest way of doing this is to use
+the :command:`ipcluster` command::
 
-	$ ipcluster -n 4
+	$ ipcluster local -n 4
 	
-For more detailed information about starting the controller and engines, see our :ref:`introduction <ip1par>` to using IPython for parallel computing.
+For more detailed information about starting the controller and engines, see
+our :ref:`introduction <ip1par>` to using IPython for parallel computing.
 
-The magic here is that this single controller and set of engines is running both the MultiEngine and ``Task`` interfaces simultaneously.
+Creating a ``TaskClient`` instance
+=========================================
 
-QuickStart Task Farming
-=======================
+The first step is to import the IPython :mod:`IPython.kernel.client` module
+and then create a :class:`TaskClient` instance:
 
-First, a quick example of how to start running the most basic Tasks.
-The first step is to import the IPython ``client`` module and then create a ``TaskClient`` instance::
-    
-    In [1]: from IPython.kernel import client
-    
-    In [2]: tc = client.TaskClient()
+.. sourcecode:: ipython
 
-Then the user wrap the commands the user want to run in Tasks::
+	In [1]: from IPython.kernel import client
+	
+	In [2]: tc = client.TaskClient()
+
+This form assumes that the :file:`ipcontroller-tc.furl` is in the
+:file:`~./ipython/security` directory on the client's host. If not, the
+location of the FURL file must be given as an argument to the
+constructor:
+
+.. sourcecode:: ipython
+
+    In [2]: mec = client.TaskClient('/path/to/my/ipcontroller-tc.furl')
+
+Quick and easy parallelism
+==========================
+
+In many cases, you simply want to apply a Python function to a sequence of objects, but *in parallel*.  Like the multiengine interface, the task interface provides two simple ways of accomplishing this:  a parallel version of :func:`map` and ``@parallel`` function decorator.  However, the verions in the task interface have one important difference:  they are dynamically load balanced.  Thus, if the execution time per item varies significantly, you should use the versions in the task interface.
+
+Parallel map
+------------
+
+The parallel :meth:`map` in the task interface is similar to that in the multiengine interface:
+
+.. sourcecode:: ipython
+
+	In [63]: serial_result = map(lambda x:x**10, range(32))
+
+	In [64]: parallel_result = tc.map(lambda x:x**10, range(32))
+
+	In [65]: serial_result==parallel_result
+	Out[65]: True
+
+Parallel function decorator
+---------------------------
+
+Parallel functions are just like normal function, but they can be called on sequences and *in parallel*.  The multiengine interface provides a decorator that turns any Python function into a parallel function:
+
+.. sourcecode:: ipython
+
+    In [10]: @tc.parallel()
+       ....: def f(x):
+       ....:     return 10.0*x**4
+       ....: 
+
+    In [11]: f(range(32))    # this is done in parallel
+    Out[11]: 
+    [0.0,10.0,160.0,...]
+
+More details
+============
+
+The :class:`TaskClient` has many more powerful features that allow quite a bit of flexibility in how tasks are defined and run.  The next places to look are in the following classes:
 
-    In [3]: tasklist = []
-    In [4]: for n in range(1000):
-        ...     tasklist.append(client.Task("a = %i"%n, pull="a"))
+* :class:`IPython.kernel.client.TaskClient`
+* :class:`IPython.kernel.client.StringTask`
+* :class:`IPython.kernel.client.MapTask`
 
-The first argument of the ``Task`` constructor is a string, the command to be executed.  The most important optional keyword argument is ``pull``, which can be a string or list of strings, and it specifies the variable names to be saved as results of the ``Task``.
+The following is an overview of how to use these classes together:
 
-Next, the user need to submit the Tasks to the ``TaskController`` with the ``TaskClient``::
+1. Create a :class:`TaskClient`.
+2. Create one or more instances of :class:`StringTask` or :class:`MapTask`
+   to define your tasks.
+3. Submit your tasks to using the :meth:`run` method of your
+   :class:`TaskClient` instance.
+4. Use :meth:`TaskClient.get_task_result` to get the results of the
+   tasks.
 
-    In [5]: taskids = [ tc.run(t) for t in tasklist ]
+We are in the process of developing more detailed information about the task interface.  For now, the docstrings of the :class:`TaskClient`, :class:`StringTask` and :class:`MapTask` classes should be consulted.
 
-This will give the user a list of the TaskIDs used by the controller to keep track of the Tasks and their results.  Now at some point the user are going to want to get those results back.  The ``barrier`` method allows the user to wait for the Tasks to finish running::
-
-    In [6]: tc.barrier(taskids)
-
-This command will block until all the Tasks in ``taskids`` have finished.  Now, the user probably want to look at the user's results::
-
-    In [7]: task_results = [ tc.get_task_result(taskid) for taskid in taskids ]
-
-Now the user have a list of ``TaskResult`` objects, which have the actual result as a dictionary, but also keep track of some useful metadata about the ``Task``::
-
-    In [8]: tr = ``Task``_results[73]
-    
-    In [9]: tr
-    Out[9]: ``TaskResult``[ID:73]:{'a':73}
-    
-    In [10]: tr.engineid
-    Out[10]: 1
-    
-    In [11]: tr.submitted, tr.completed, tr.duration
-    Out[11]: ("2008/03/08 03:41:42", "2008/03/08 03:41:44", 2.12345)
-
-The actual results are stored in a dictionary, ``tr.results``, and a namespace object ``tr.ns`` which accesses the result keys by attribute::
-
-    In [12]: tr.results['a']
-    Out[12]: 73
-    
-    In [13]: tr.ns.a
-    Out[13]: 73
-
-That should cover the basics of running simple Tasks.  There are several more powerful things the user can do with Tasks covered later.  The most useful probably being using a ``MutiEngineClient`` interface to initialize all the engines with the import dependencies necessary to run the user's Tasks.
-
-There are many options for running and managing Tasks. The best way to learn further about the ``Task`` interface is to study the examples in ``docs/examples``. If the user do so and learn a lots about this interface, we encourage the user to expand this documentation about the ``Task`` system.
-
-Overview of the Task System
-===========================
-
-The user's view of the ``Task`` system has three basic objects:  The ``TaskClient``, the ``Task``, and the ``TaskResult``.  The names of these three objects well indicate their role.
-
-The ``TaskClient`` is the user's ``Task`` farming connection to the IPython cluster.  Unlike the ``MultiEngineClient``, the ``TaskControler`` handles all the scheduling and distribution of work, so the ``TaskClient`` has no notion of engines, it just submits Tasks and requests their results.  The Tasks are described as ``Task`` objects, and their results are wrapped in ``TaskResult`` objects.  Thus, there are very few necessary methods for the user to manage.
-
-Inside the task system is a Scheduler object, which assigns tasks to workers.  The default scheduler is a simple FIFO queue.  Subclassing the Scheduler should be easy, just implementing your own priority system.
-
-The TaskClient
-==============
-
-The ``TaskClient`` is the object the user use to connect to the ``Controller`` that is managing the user's Tasks.  It is the analog of the ``MultiEngineClient`` for the standard IPython multiplexing interface.  As with all client interfaces, the first step is to import the IPython Client Module::
-
-    In [1]: from IPython.kernel import client
-
-Just as with the ``MultiEngineClient``, the user create the ``TaskClient`` with a tuple, containing the ip-address and port of the ``Controller``.  the ``client`` module conveniently has the default address of the ``Task`` interface of the controller.  Creating a default ``TaskClient`` object would be done with this::
-
-    In [2]: tc = client.TaskClient(client.default_task_address)
-
-or, if the user want to specify a non default location of the ``Controller``, the user can specify explicitly::
-
-    In [3]: tc = client.TaskClient(("192.168.1.1", 10113))
-
-As discussed earlier, the ``TaskClient`` only has a few basic methods.
-
- * ``tc.run(task)``
-    ``run`` is the method by which the user submits Tasks.  It takes exactly one argument, a ``Task`` object.  All the advanced control of ``Task`` behavior is handled by properties of the ``Task`` object, rather than the submission command, so they will be discussed later in the `Task`_ section.  ``run`` returns an integer, the ``Task``ID by which the ``Task`` and its results can be tracked and retrieved::
-    
-        In [4]: ``Task``ID = tc.run(``Task``)
-    
- * ``tc.get_task_result(taskid, block=``False``)``
-    ``get_task_result`` is the method by which results are retrieved.  It takes a single integer argument, the ``Task``ID`` of the result the user wish to retrieve.  ``get_task_result`` also takes a keyword argument ``block``.  ``block`` specifies whether the user actually want to wait for the result.  If ``block`` is false, as it is by default, ``get_task_result`` will return immediately.  If the ``Task`` has completed, it will return the ``TaskResult`` object for that ``Task``.  But if the ``Task`` has not completed, it will return ``None``.  If the user specify ``block=``True``, then ``get_task_result`` will wait for the ``Task`` to complete, and always return the ``TaskResult`` for the requested ``Task``.
- * ``tc.barrier(taskid(s))``
-    ``barrier`` is a synchronization method.  It takes exactly one argument, a ``Task``ID or list of taskIDs.  ``barrier`` will block until all the specified Tasks have completed.  In practice, a barrier is often called between the ``Task`` submission section of the code and the result gathering section::
-        
-        In [5]: taskIDs = [ tc.run(``Task``) for ``Task`` in myTasks ]
-        
-        In [6]: tc.get_task_result(taskIDs[-1]) is None
-        Out[6]: ``True``
-        
-        In [7]: tc.barrier(``Task``ID)
-        
-        In [8]: results = [ tc.get_task_result(tid) for tid in taskIDs ]
-        
- * ``tc.queue_status(verbose=``False``)``
-    ``queue_status`` is a method for querying the state of the ``TaskControler``.  ``queue_status`` returns a dict of the form::
-        
-        {'scheduled': Tasks that have been submitted but yet run
-         'pending'  : Tasks that are currently running
-         'succeeded': Tasks that have completed successfully
-         'failed'   : Tasks that have finished with a failure
-        }
-    
-    if @verbose is not specified (or is ``False``), then the values of the dict are integers - the number of Tasks in each state.  if @verbose is ``True``, then each element in the dict is a list of the taskIDs in that state::
-    
-        In [8]: tc.queue_status()
-        Out[8]: {'scheduled': 4,
-                'pending'  : 2,
-                'succeeded': 5,
-                'failed'   : 1
-                }
-        
-        In [9]: tc.queue_status(verbose=True)
-        Out[9]: {'scheduled': [8,9,10,11],
-                'pending'  : [6,7],
-                'succeeded': [0,1,2,4,5],
-                'failed'   : [3]
-                }
-        
- * ``tc.abort(taskid)``
-    ``abort`` allows the user to abort Tasks that have already been submitted.  ``abort`` will always return immediately.  If the ``Task`` has completed, ``abort`` will raise an ``IndexError ``Task`` Already Completed``.  An obvious case for ``abort`` would be where the user submits a long-running ``Task`` with a number of retries (see ``Task``_ section for how to specify retries) in an interactive session, but realizes there has been a typo.  The user can then abort the ``Task``, preventing certain failures from cluttering up the queue.  It can also be used for parallel search-type problems, where only one ``Task`` will give the solution, so once the user find the solution, the user would want to abort all remaining Tasks to prevent wasted work.
- * ``tc.spin()``
-    ``spin`` simply triggers the scheduler in the ``TaskControler``.  Under most normal circumstances, this will do nothing.  The primary known usage case involves the ``Task`` dependency (see `Dependencies`_).  The dependency is a function of an Engine's ``properties``, but changing the ``properties`` via the ``MutliEngineClient`` does not trigger a reschedule event.  The main example case for this requires the following event sequence:
-     * ``engine`` is available, ``Task`` is submitted, but ``engine`` does not have ``Task``'s dependencies.
-     * ``engine`` gets necessary dependencies while no new Tasks are submitted or completed.
-     * now ``engine`` can run ``Task``, but a ``Task`` event is required for the ``TaskControler`` to try scheduling ``Task`` again.
-     
-    ``spin`` is just an empty ping method to ensure that the Controller has scheduled all available Tasks, and should not be needed under most normal circumstances.
-
-That covers the ``TaskClient``, a simple interface to the cluster.  With this, the user can submit jobs (and abort if necessary), request their results, synchronize on arbitrary subsets of jobs.
-
-.. _task: The Task Object
-
-The Task Object
-===============
-
-The ``Task`` is the basic object for describing a job.  It can be used in a very simple manner, where the user just specifies a command string to be executed as the ``Task``.  The usage of this first argument is exactly the same as the ``execute`` method of the ``MultiEngine`` (in fact, ``execute`` is called to run the code)::
-
-    In [1]: t = client.Task("a = str(id)")
-    
-This ``Task`` would run, and store the string representation of the ``id`` element in ``a`` in each worker's namespace, but it is fairly useless because the user does not know anything about the state of the ``worker`` on which it ran at the time of retrieving results.  It is important that each ``Task`` not expect the state of the ``worker`` to persist after the ``Task`` is completed.  
-There are many different situations for using ``Task`` Farming, and the ``Task`` object has many attributes for use in customizing the ``Task`` behavior.  All of a ``Task``'s attributes may be specified in the constructor, through keyword arguments, or after ``Task`` construction through attribute assignment.
-
-Data Attributes
-***************
-It is likely that the user may want to move data around before or after executing the ``Task``.  We provide methods of sending data to initialize the worker's namespace, and specifying what data to bring back as the ``Task``'s results.
-
- * pull = []
-    The obvious case is as above, where ``t`` would execute and store the result of ``myfunc`` in ``a``, it is likely that the user would want to bring ``a`` back to their namespace.  This is done through the ``pull`` attribute.  ``pull`` can be a string or list of strings, and it specifies the names of variables to be retrieved.  The ``TaskResult`` object retrieved by ``get_task_result`` will have a dictionary of keys and values, and the ``Task``'s ``pull`` attribute determines what goes into it::
-        
-        In [2]: t = client.Task("a = str(id)", pull = "a")
-        
-        In [3]: t = client.Task("a = str(id)", pull = ["a", "id"])
-        
- * push = {}
-    A user might also want to initialize some data into the namespace before the code part of the ``Task`` is run.  Enter ``push``.  ``push`` is a dictionary of key/value pairs to be loaded from the user's namespace into the worker's immediately before execution::
-
-        In [4]: t = client.Task("a = f(submitted)", push=dict(submitted=time.time()), pull="a")
-
-push and pull result directly in calling an ``engine``'s ``push`` and ``pull`` methods before and after ``Task`` execution respectively, and thus their api is the same.
-
-Namespace Cleaning
-******************
-When a user is running a large number of Tasks, it is likely that the namespace of the worker's could become cluttered.  Some Tasks might be sensitive to clutter, while others might be known to cause namespace pollution.  For these reasons, Tasks have two boolean attributes for cleaning up the namespace.
-
- * ``clear_after``
-    if clear_after is specified ``True``, the worker on which the ``Task`` was run will be reset (via ``engine.reset``) upon completion of the ``Task``.  This can be useful for both Tasks that produce clutter or Tasks whose intermediate data one might wish to be kept private::
-    
-        In [5]: t = client.Task("a = range(1e10)", pull = "a",clear_after=True)
-        
-    
- * ``clear_before``
-    as one might guess, clear_before is identical to ``clear_after``, but it takes place before the ``Task`` is run.  This ensures that the ``Task`` runs on a fresh worker::
-
-        In [6]: t = client.Task("a = globals()", pull = "a",clear_before=True)
-
-Of course, a user can both at the same time, ensuring that all workers are clear except when they are currently running a job.  Both of these default to ``False``.
-
-Fault Tolerance
-***************
-It is possible that Tasks might fail, and there are a variety of reasons this could happen.  One might be that the worker it was running on disconnected, and there was nothing wrong with the ``Task`` itself.  With the fault tolerance attributes of the ``Task``, the user can specify how many times to resubmit the ``Task``, and what to do if it never succeeds.
-
- * ``retries``
-    ``retries`` is an integer, specifying the number of times a ``Task`` is to be retried.  It defaults to zero.  It is often a good idea for this number to be 1 or 2, to protect the ``Task`` from disconnecting engines, but not a large number.  If a ``Task`` is failing 100 times, there is probably something wrong with the ``Task``.  The canonical bad example:
-    
-        In [7]: t = client.Task("os.kill(os.getpid(), 9)", retries=99)
-        
-    This would actually take down 100 workers.
-    
- * ``recovery_task``
-    ``recovery_task`` is another ``Task`` object, to be run in the event of the original ``Task`` still failing after running out of retries.  Since ``recovery_task`` is another ``Task`` object, it can have its own ``recovery_task``.  The chain of Tasks is limitless, except loops are not allowed (that would be bad!).
-
-Dependencies
-************
-Dependencies are the most powerful part of the ``Task`` farming system, because it allows the user to do some classification of the workers, and guide the ``Task`` distribution without meddling with the controller directly.  It makes use of two objects - the ``Task``'s ``depend`` attribute, and the engine's ``properties``.  See the `MultiEngine`_ reference for how to use engine properties.  The engine properties api exists for extending IPython, allowing conditional execution and new controllers that make decisions based on properties of its engines.  Currently the ``Task`` dependency is the only internal use of the properties api.
-
-.. _MultiEngine: ./parallel_multiengine
-
-The ``depend`` attribute of a ``Task`` must be a function of exactly one argument, the worker's properties dictionary, and it should return ``True`` if the ``Task`` should be allowed to run on the worker and ``False`` if not.  The usage in the controller is fault tolerant, so exceptions raised by ``Task.depend`` will be ignored and functionally equivalent to always returning ``False``.  Tasks`` with invalid ``depend`` functions will never be assigned to a worker::
-
-    In [8]: def dep(properties):
-        ...     return properties["RAM"] > 2**32 # have at least 4GB
-    In [9]: t = client.Task("a = bigfunc()", depend=dep)
-    
-It is important to note that assignment of values to the properties dict is done entirely by the user, either locally (in the engine) using the EngineAPI, or remotely, through the ``MultiEngineClient``'s get/set_properties methods.
-
-
-
-
-
-    

scripts/ipython_win_post_install.py

@@ -1,85 +1,106
 #!python
 """Windows-specific part of the installation"""
 
 import os, sys, shutil
+pjoin = os.path.join
 
 def mkshortcut(target,description,link_file,*args,**kw):
     """make a shortcut if it doesn't exist, and register its creation"""
     
     create_shortcut(target, description, link_file,*args,**kw)
     file_created(link_file)
 
 def install():
     """Routine to be run by the win32 installer with the -install switch."""
-
+    
     from IPython.Release import version
-
+    
     # Get some system constants
     prefix = sys.prefix
-    python = prefix + r'\python.exe'
-    # Lookup path to common startmenu ...
-    ip_dir = get_special_folder_path('CSIDL_COMMON_PROGRAMS') + r'\IPython'
+    python = pjoin(prefix, 'python.exe')
     
-    # Some usability warnings at installation time.  I don't want them at the
-    # top-level, so they don't appear if the user is uninstalling.
-    try:
-        import ctypes
-    except ImportError:
-        print ('To take full advantage of IPython, you need ctypes from:\n'
-               'http://sourceforge.net/projects/ctypes')
-
-    try:
-        import win32con
-    except ImportError:
-        print ('To take full advantage of IPython, you need pywin32 from:\n'
-               'http://starship.python.net/crew/mhammond/win32/Downloads.html')
-
-    try:
-        import readline
-    except ImportError:
-        print ('To take full advantage of IPython, you need readline from:\n'
-               'http://sourceforge.net/projects/uncpythontools')
-
-    ipybase = '"'+prefix+r'\scripts\ipython"'
+    # Lookup path to common startmenu ...
+    ip_start_menu = pjoin(get_special_folder_path('CSIDL_COMMON_PROGRAMS'), 'IPython')
     # Create IPython entry ...
-    if not os.path.isdir(ip_dir):
-        os.mkdir(ip_dir)
-        directory_created(ip_dir)
-
-    # Create program shortcuts ...
-    f = ip_dir + r'\IPython.lnk'
-    a = ipybase
-    mkshortcut(python,'IPython',f,a)
-
-    f = ip_dir + r'\pysh.lnk'
-    a = ipybase+' -p sh'
-    mkshortcut(python,'IPython command prompt mode',f,a)
-
-    f = ip_dir + r'\scipy.lnk'
-    a = ipybase+' -pylab -p scipy'
-    mkshortcut(python,'IPython scipy profile',f,a)
+    if not os.path.isdir(ip_start_menu):
+        os.mkdir(ip_start_menu)
+        directory_created(ip_start_menu)
+    
+    # Create .py and .bat files to make things available from
+    # the Windows command line.  Thanks to the Twisted project
+    # for this logic!
+    programs = [
+        'ipython',
+        'iptest',
+        'ipcontroller',
+        'ipengine',
+        'ipcluster',
+        'ipythonx',
+        'ipython-wx',
+        'irunner'
+    ]
+    scripts = pjoin(prefix,'scripts')
+    for program in programs:
+        raw = pjoin(scripts, program)
+        bat = raw + '.bat'
+        py = raw + '.py'
+        # Create .py versions of the scripts
+        shutil.copy(raw, py)
+        # Create .bat files for each of the scripts
+        bat_file = file(bat,'w')
+        bat_file.write("@%s %s %%*" % (python, py))
+        bat_file.close()
+            
+    # Now move onto setting the Start Menu up
+    ipybase = pjoin(scripts, 'ipython')
 
-    # Create documentation shortcuts ...    
+    link = pjoin(ip_start_menu, 'IPython.lnk')
+    cmd = '"%s"' % ipybase
+    mkshortcut(python,'IPython',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'pysh.lnk')
+    cmd = '"%s" -p sh' % ipybase
+    mkshortcut(python,'IPython (command prompt mode)',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'pylab.lnk')
+    cmd = '"%s" -pylab' % ipybase
+    mkshortcut(python,'IPython (PyLab mode)',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'scipy.lnk')
+    cmd = '"%s" -pylab -p scipy' % ipybase
+    mkshortcut(python,'IPython (scipy profile)',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'IPython test suite.lnk')
+    cmd = '"%s" -vv' % pjoin(scripts, 'iptest')
+    mkshortcut(python,'Run the IPython test suite',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'ipcontroller.lnk')
+    cmd = '"%s" -xy' % pjoin(scripts, 'ipcontroller')
+    mkshortcut(python,'IPython controller',link,cmd)
+    
+    link = pjoin(ip_start_menu, 'ipengine.lnk')
+    cmd = '"%s"' % pjoin(scripts, 'ipengine')
+    mkshortcut(python,'IPython engine',link,cmd)
+    
+    # Create documentation shortcuts ...
     t = prefix + r'\share\doc\ipython\manual\ipython.pdf'
-    f = ip_dir + r'\Manual in PDF.lnk'
+    f = ip_start_menu + r'\Manual in PDF.lnk'
     mkshortcut(t,r'IPython Manual - PDF-Format',f)
-
-    t = prefix + r'\share\doc\ipython\manual\ipython.html'
-    f = ip_dir + r'\Manual in HTML.lnk'
+    
+    t = prefix + r'\share\doc\ipython\manual\html\index.html'
+    f = ip_start_menu + r'\Manual in HTML.lnk'
     mkshortcut(t,'IPython Manual - HTML-Format',f)
-
-    # make ipython.py
-    shutil.copy(prefix + r'\scripts\ipython', prefix + r'\scripts\ipython.py')
+    
     
 def remove():
     """Routine to be run by the win32 installer with the -remove switch."""
     pass
 
 # main()
 if len(sys.argv) > 1:
     if sys.argv[1] == '-install':
         install()
     elif sys.argv[1] == '-remove':
         remove()
     else:
         print "Script was called with option %s" % sys.argv[1]

setup.py

@@ -1,179 +1,189
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """Setup script for IPython.
 
 Under Posix environments it works like a typical setup.py script. 
 Under Windows, the command sdist is not supported, since IPython 
 requires utilities which are not available under Windows."""
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 
 # Stdlib imports
 import os
 import sys
 
 from glob import glob
 
 # BEFORE importing distutils, remove MANIFEST. distutils doesn't properly
 # update it when the contents of directories change.
 if os.path.exists('MANIFEST'): os.remove('MANIFEST')
 
 from distutils.core import setup
 
 # Local imports
 from IPython.genutils import target_update
 
 from setupbase import (
     setup_args, 
     find_packages, 
     find_package_data, 
     find_scripts,
     find_data_files,
     check_for_dependencies
 )
 
 isfile = os.path.isfile
 
 #-------------------------------------------------------------------------------
 # Handle OS specific things
 #-------------------------------------------------------------------------------
 
 if os.name == 'posix':
     os_name = 'posix'
 elif os.name in ['nt','dos']:
     os_name = 'windows'
 else:
     print 'Unsupported operating system:',os.name
     sys.exit(1)
 
 # Under Windows, 'sdist' has not been supported.  Now that the docs build with
 # Sphinx it might work, but let's not turn it on until someone confirms that it
 # actually works.
 if os_name == 'windows' and 'sdist' in sys.argv:
     print 'The sdist command is not available under Windows.  Exiting.'
     sys.exit(1)
 
 #-------------------------------------------------------------------------------
 # Things related to the IPython documentation
 #-------------------------------------------------------------------------------
 
 # update the manuals when building a source dist
 if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'):
     import textwrap
 
     # List of things to be updated. Each entry is a triplet of args for
     # target_update()
     to_update = [
                   # FIXME - Disabled for now: we need to redo an automatic way
                   # of generating the magic info inside the rst.                
                   #('docs/magic.tex',
                   #['IPython/Magic.py'],
                   #"cd doc && ./update_magic.sh" ),
                  
                  ('docs/man/ipython.1.gz',
                   ['docs/man/ipython.1'],
                   "cd docs/man && gzip -9c ipython.1 > ipython.1.gz"),
 
                  ('docs/man/pycolor.1.gz',
                   ['docs/man/pycolor.1'],
                   "cd docs/man && gzip -9c pycolor.1 > pycolor.1.gz"),
                  ]
 
-    # Only build the docs is sphinx is present
+    # Only build the docs if sphinx is present
     try:
         import sphinx
     except ImportError:
         pass
     else:
-        pass
-        # BEG: This is disabled as I am not sure what to depend on.
-        # I actually don't think we should be automatically building
-        # the docs for people.
-        # The do_sphinx scripts builds html and pdf, so just one
-        # target is enough to cover all manual generation
-        # to_update.append(
-        #     ('docs/manual/ipython.pdf',
-        #     ['IPython/Release.py','docs/source/ipython.rst'],
-        #     "cd docs && python do_sphinx.py")
-        # )
+        # The Makefile calls the do_sphinx scripts to build html and pdf, so
+        # just one target is enough to cover all manual generation
+
+        # First, compute all the dependencies that can force us to rebuild the
+        # docs.  Start with the main release file that contains metadata
+        docdeps = ['IPython/Release.py']
+        # Inculde all the reST sources
+        pjoin = os.path.join
+        for dirpath,dirnames,filenames in os.walk('docs/source'):
+            if dirpath in ['_static','_templates']:
+                continue
+            docdeps += [ pjoin(dirpath,f) for f in filenames
+                         if f.endswith('.txt') ]
+        # and the examples
+        for dirpath,dirnames,filenames in os.walk('docs/example'):
+            docdeps += [ pjoin(dirpath,f) for f in filenames
+                         if not f.endswith('~') ]
+        # then, make them all dependencies for the main PDF (the html will get
+        # auto-generated as well).
+        to_update.append(
+            ('docs/dist/ipython.pdf',
+             docdeps,
+             "cd docs && make dist")
+            )
         
     [ target_update(*t) for t in to_update ]
 
-    # Build the docs
-    os.system('cd docs && make dist')
     
 #---------------------------------------------------------------------------
 # Find all the packages, package data, scripts and data_files
 #---------------------------------------------------------------------------
 
 packages = find_packages()
 package_data = find_package_data()
 scripts = find_scripts()
 data_files = find_data_files()
 
 #---------------------------------------------------------------------------
 # Handle dependencies and setuptools specific things
 #---------------------------------------------------------------------------
 
 # This dict is used for passing extra arguments that are setuptools 
 # specific to setup
 setuptools_extra_args = {}
 
 if 'setuptools' in sys.modules:
     setuptools_extra_args['zip_safe'] = False
     setuptools_extra_args['entry_points'] = {
         'console_scripts': [
             'ipython = IPython.ipapi:launch_new_instance',
             'pycolor = IPython.PyColorize:main',
             'ipcontroller = IPython.kernel.scripts.ipcontroller:main',
             'ipengine = IPython.kernel.scripts.ipengine:main',
             'ipcluster = IPython.kernel.scripts.ipcluster:main',
-            'ipythonx = IPython.frontend.wx.ipythonx:main'
+            'ipythonx = IPython.frontend.wx.ipythonx:main',
+            'iptest = IPython.testing.iptest:main',
         ]
     }
-    setup_args["extras_require"] = dict(
+    setup_args['extras_require'] = dict(
         kernel = [
-            "zope.interface>=3.4.1",
-            "Twisted>=8.0.1",
-            "foolscap>=0.2.6"        
+            'zope.interface>=3.4.1',
+            'Twisted>=8.0.1',
+            'foolscap>=0.2.6'
         ],
-        doc=['Sphinx>=0.3','pygments'],
+        doc='Sphinx>=0.3',
         test='nose>=0.10.1',
-        security=["pyOpenSSL>=0.6"]
+        security='pyOpenSSL>=0.6'
     )
     # Allow setuptools to handle the scripts
     scripts = []
-    # eggs will lack docs, examples
-    data_files = []
 else:
     # package_data of setuptools was introduced to distutils in 2.4
     cfgfiles = filter(isfile, glob('IPython/UserConfig/*'))
     if sys.version_info < (2,4):
         data_files.append(('lib', 'IPython/UserConfig', cfgfiles))
     # If we are running without setuptools, call this function which will
     # check for dependencies an inform the user what is needed.  This is
     # just to make life easy for users.
     check_for_dependencies()
 
 
 #---------------------------------------------------------------------------
 # Do the actual setup now
 #---------------------------------------------------------------------------
 
 setup_args['packages'] = packages
 setup_args['package_data'] = package_data
 setup_args['scripts'] = scripts
 setup_args['data_files'] = data_files
 setup_args.update(setuptools_extra_args)
 
 if __name__ == '__main__':
     setup(**setup_args)

setupbase.py

@@ -1,275 +1,279
 # encoding: utf-8
 
 """
 This module defines the things that are used in setup.py for building IPython
 
 This includes:
 
     * The basic arguments to setup
     * Functions for finding things like packages, package data, etc.
     * A function for checking dependencies.
 """
 
 __docformat__ = "restructuredtext en"
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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 os, sys
 
 from glob import glob
 
 from setupext import install_data_ext
 
 #-------------------------------------------------------------------------------
 # Useful globals and utility functions
 #-------------------------------------------------------------------------------
 
 # A few handy globals
 isfile = os.path.isfile
 pjoin = os.path.join
 
 def oscmd(s):
     print ">", s
     os.system(s)
 
 # A little utility we'll need below, since glob() does NOT allow you to do
 # exclusion on multiple endings!
 def file_doesnt_endwith(test,endings):
     """Return true if test is a file and its name does NOT end with any
     of the strings listed in endings."""
     if not isfile(test):
         return False
     for e in endings:
         if test.endswith(e):
             return False
     return True
 
 #---------------------------------------------------------------------------
 # Basic project information
 #---------------------------------------------------------------------------
 
 # Release.py contains version, authors, license, url, keywords, etc.
 execfile(pjoin('IPython','Release.py'))
 
 # Create a dict with the basic information
 # This dict is eventually passed to setup after additional keys are added.
 setup_args = dict(
       name             = name,
       version          = version,
       description      = description,
       long_description = long_description,
       author           = author,
       author_email     = author_email,
       url              = url,
       download_url     = download_url,
       license          = license,
       platforms        = platforms,
       keywords         = keywords,
       cmdclass         = {'install_data': install_data_ext},
       )
 
 
 #---------------------------------------------------------------------------
 # Find packages
 #---------------------------------------------------------------------------
 
 def add_package(packages,pname,config=False,tests=False,scripts=False,
                 others=None):
     """
     Add a package to the list of packages, including certain subpackages.
     """
     packages.append('.'.join(['IPython',pname]))
     if config:
         packages.append('.'.join(['IPython',pname,'config']))
     if tests:
         packages.append('.'.join(['IPython',pname,'tests']))
     if scripts:
         packages.append('.'.join(['IPython',pname,'scripts']))
     if others is not None:
         for o in others:
             packages.append('.'.join(['IPython',pname,o]))
 
 def find_packages():
     """
     Find all of IPython's packages.
     """
     packages = ['IPython']
     add_package(packages, 'config', tests=True)
     add_package(packages , 'Extensions')
     add_package(packages, 'external')
     add_package(packages, 'gui')
     add_package(packages, 'gui.wx')
     add_package(packages, 'frontend', tests=True)
     add_package(packages, 'frontend._process')
     add_package(packages, 'frontend.wx')
     add_package(packages, 'frontend.cocoa', tests=True)
     add_package(packages, 'kernel', config=True, tests=True, scripts=True)
     add_package(packages, 'kernel.core', config=True, tests=True)
     add_package(packages, 'testing', tests=True)
+    add_package(packages, 'tests')
+    add_package(packages, 'testing.plugin', tests=False)
     add_package(packages, 'tools', tests=True)
     add_package(packages, 'UserConfig')
     return packages
 
 #---------------------------------------------------------------------------
 # Find package data
 #---------------------------------------------------------------------------
 
 def find_package_data():
     """
     Find IPython's package_data.
     """
     # This is not enough for these things to appear in an sdist.
     # We need to muck with the MANIFEST to get this to work
     package_data = {
         'IPython.UserConfig' : ['*'],
         'IPython.tools.tests' : ['*.txt'],
         'IPython.testing' : ['*.txt']
     }
     return package_data
 
 
 #---------------------------------------------------------------------------
 # Find data files
 #---------------------------------------------------------------------------
 
 def make_dir_struct(tag,base,out_base):
     """Make the directory structure of all files below a starting dir.
 
     This is just a convenience routine to help build a nested directory
     hierarchy because distutils is too stupid to do this by itself.
 
     XXX - this needs a proper docstring!
     """
     
     # we'll use these a lot below
     lbase = len(base)
     pathsep = os.path.sep
     lpathsep = len(pathsep)
     
     out = []
     for (dirpath,dirnames,filenames) in os.walk(base):
         # we need to strip out the dirpath from the base to map it to the
         # output (installation) path.  This requires possibly stripping the
         # path separator, because otherwise pjoin will not work correctly
         # (pjoin('foo/','/bar') returns '/bar').
         
         dp_eff = dirpath[lbase:]
         if dp_eff.startswith(pathsep):
             dp_eff = dp_eff[lpathsep:]
         # The output path must be anchored at the out_base marker    
         out_path = pjoin(out_base,dp_eff)
         # Now we can generate the final filenames. Since os.walk only produces
         # filenames, we must join back with the dirpath to get full valid file
         # paths:
         pfiles = [pjoin(dirpath,f) for f in filenames]
         # Finally, generate the entry we need, which is a triple of (tag,output
         # path, files) for use as a data_files parameter in install_data.
         out.append((tag,out_path,pfiles))
 
     return out
     
 
 def find_data_files():
     """
     Find IPython's data_files.
 
     Most of these are docs.
     """
     
     docdirbase  = 'share/doc/ipython'
     manpagebase = 'share/man/man1'
 
     # Simple file lists can be made by hand
     manpages  = filter(isfile, glob('docs/man/*.1.gz'))
     igridhelpfiles = filter(isfile, glob('IPython/Extensions/igrid_help.*'))
 
     # For nested structures, use the utility above
     example_files = make_dir_struct('data','docs/examples',
                                     pjoin(docdirbase,'examples'))
     manual_files = make_dir_struct('data','docs/dist',pjoin(docdirbase,'manual'))
 
     # And assemble the entire output list
     data_files = [ ('data',manpagebase, manpages),
                    ('data',pjoin(docdirbase,'extensions'),igridhelpfiles),
                    ] + manual_files + example_files
                  
     ## import pprint  # dbg
     ## print '*'*80
     ## print 'data files'
     ## pprint.pprint(data_files)
     ## print '*'*80
     
     return data_files
 
 #---------------------------------------------------------------------------
 # Find scripts
 #---------------------------------------------------------------------------
 
 def find_scripts():
     """
     Find IPython's scripts.
     """
     scripts = ['IPython/kernel/scripts/ipengine',
                'IPython/kernel/scripts/ipcontroller',
-                'IPython/kernel/scripts/ipcluster',
+               'IPython/kernel/scripts/ipcluster',
                'scripts/ipython',
                'scripts/ipythonx',
+               'scripts/ipython-wx',
                'scripts/pycolor',
                'scripts/irunner',
+               'scripts/iptest',
                ]
     
     # Script to be run by the windows binary installer after the default setup
     # routine, to add shortcuts and similar windows-only things.  Windows
     # post-install scripts MUST reside in the scripts/ dir, otherwise distutils
     # doesn't find them.
     if 'bdist_wininst' in sys.argv:
         if len(sys.argv) > 2 and ('sdist' in sys.argv or 'bdist_rpm' in sys.argv):
             print >> sys.stderr,"ERROR: bdist_wininst must be run alone. Exiting."
             sys.exit(1)
         scripts.append('scripts/ipython_win_post_install.py')
     
     return scripts
 
 #---------------------------------------------------------------------------
 # Verify all dependencies
 #---------------------------------------------------------------------------
 
 def check_for_dependencies():
     """Check for IPython's dependencies.
     
     This function should NOT be called if running under setuptools!
     """
     from setupext.setupext import (
         print_line, print_raw, print_status, print_message,
         check_for_zopeinterface, check_for_twisted,
         check_for_foolscap, check_for_pyopenssl,
         check_for_sphinx, check_for_pygments,
         check_for_nose, check_for_pexpect
     )
     print_line()
     print_raw("BUILDING IPYTHON")
     print_status('python', sys.version)
     print_status('platform', sys.platform)
     if sys.platform == 'win32':
         print_status('Windows version', sys.getwindowsversion())
     
     print_raw("")
     print_raw("OPTIONAL DEPENDENCIES")
 
     check_for_zopeinterface()
     check_for_twisted()
     check_for_foolscap()
     check_for_pyopenssl()
     check_for_sphinx()
     check_for_pygments()
     check_for_nose()
     check_for_pexpect()

setupegg.py

@@ -1,20 +1,14
 #!/usr/bin/env python
 """Wrapper to run setup.py using setuptools."""
 
-import os
 import sys
 
-# Add my local path to sys.path
-home = os.environ['HOME']
-sys.path.insert(0,'%s/usr/local/lib/python%s/site-packages' %
-                (home,sys.version[:3]))
-
 # now, import setuptools and call the actual setup
 import setuptools
 # print sys.argv
 #sys.argv=['','bdist_egg']
 execfile('setup.py')
 
 # clean up the junk left around by setuptools
 if "develop" not in sys.argv:
     os.system('rm -rf ipython.egg-info build')

tools/check_sources.py

@@ -1,15 +1,15
 from IPython.external.path import path
 fs = path('..').walkfiles('*.py')
 
 for f in fs:
     errs = ''
     cont = f.bytes()
     if '\t' in cont:
         errs+='t'
 
     if '\r' in cont:
         errs+='r'
         
     if errs:
         print "%3s" % errs, f
-    
  No newline at end of file
+    

tools/release

@@ -1,101 +1,58
 #!/bin/sh
 # IPython release script
 
 PYVER=`python -V 2>&1 | awk '{print $2}' | awk -F '.' '{print $1$2}' `
 version=`ipython -Version`
 ipdir=~/ipython/ipython
 ipbackupdir=~/ipython/backup
 
 echo
 echo "Releasing IPython version $version"
 echo "=================================="
 
-echo "Marking ChangeLog with release information and making NEWS file..."
-
-# Stamp changelog and save a copy of the status at each version, in case later
-# we want the NEWS file to start from a point before the very last release (if
-# very small interim releases have no significant changes).
-
-cd $ipdir/doc
-cp ChangeLog ChangeLog.old
-cp ChangeLog ChangeLog.$version
-daystamp=`date +%Y-%m-%d`
-echo $daystamp " ***" Released version $version > ChangeLog
-echo >> ChangeLog
-cat ChangeLog.old >> ChangeLog
-rm ChangeLog.old
-
-# Build NEWS file
-echo "Changes between the last two releases (major or minor)" > NEWS
-echo "Note that this is an auto-generated diff of the ChangeLogs" >> NEWS
-echo >> NEWS
-diff ChangeLog.previous ChangeLog | grep -v '^0a' | sed 's/^> //g' >> NEWS
-cp ChangeLog ChangeLog.previous
-
-# Clean up build/dist directories
-rm -rf $ipdir/build/*
-rm -rf $ipdir/dist/*
-
 # Perform local backup
 cd $ipdir/tools
 ./make_tarball.py
 mv ipython-*.tgz $ipbackupdir
 
+# Clean up build/dist directories
+rm -rf $ipdir/build/*
+rm -rf $ipdir/dist/*
+
 # Build source and binary distros
 cd $ipdir
 ./setup.py sdist --formats=gztar
 
 # Build version-specific RPMs, where we must use the --python option to ensure
 # that the resulting RPM is really built with the requested python version (so
 # things go to lib/python2.X/...)
-python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/python2.4
-python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5
+#python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/python2.4
+#python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5
 
 # Build eggs
 python2.4 ./setup_bdist_egg.py
 python2.5 ./setup_bdist_egg.py
 
 # Call the windows build separately, so that the extra Windows scripts don't
 # get pulled into Unix builds (setup.py has code which checks for
 # bdist_wininst)
 ./setup.py bdist_wininst --install-script=ipython_win_post_install.py
 
 # Change name so retarded Vista runs the installer correctly
 rename 's/win32/win32-setup/' $ipdir/dist/*.exe
 
 # Register with the Python Package Index (PyPI)
 echo "Registering with PyPI..."
 cd $ipdir
 ./setup.py register
 
 # Upload all files
 cd $ipdir/dist
 echo "Uploading distribution files..."
 scp * [e-mail]:www/dist/
 
 echo "Uploading backup files..."
 cd $ipbackupdir
 scp `ls -1tr *tgz | tail -1` [e-mail]:www/backup/
 
-echo "Updating webpage..."
-cd $ipdir/doc
-www=~/ipython/homepage
-cp ChangeLog NEWS $www
-rm -rf $www/doc/*
-cp -r manual/ $www/doc
-cd $www
-./update
-
-# Alert package maintainers
-#echo "Alerting package maintainers..."
-#maintainers='[e-mail] [e-mail] [e-mail] [e-mail] [e-mail] [e-mail]'
-# maintainers='[e-mail]'
-
-# for email in $maintainers
-#     do
-# 	echo "Emailing $email..."
-# 	mail -s "[Package maintainer notice] A new IPython is out. Version: $version" \
-#     $email < NEWS
-#     done
-
 echo "Done!"

tools/testrel

@@ -1,37 +1,31
 #!/bin/sh
 
 # release test
 
-ipdir=~/ipython/ipython
-ipbackupdir=~/ipython/backup
+ipdir=$PWD/..
 
 cd $ipdir
 
 # Clean up build/dist directories
 rm -rf $ipdir/build/*
 rm -rf $ipdir/dist/*
 
-# Perform local backup
-cd $ipdir/tools
-./make_tarball.py
-mv ipython-*.tgz $ipbackupdir
-
 # build source distros
 cd $ipdir
 ./setup.py sdist --formats=gztar
 
 # Build rpms
-#python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/python2.4
-#python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5
+python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/python2.4
+python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5
 
 # Build eggs
 python2.4 ./setup_bdist_egg.py
 python2.5 ./setup_bdist_egg.py
 
 # Call the windows build separately, so that the extra Windows scripts don't
 # get pulled into Unix builds (setup.py has code which checks for
 # bdist_wininst)
 ./setup.py bdist_wininst --install-script=ipython_win_post_install.py
 
 # Change name so retarded Vista runs the installer correctly
 rename 's/win32/win32-setup/' $ipdir/dist/*.exe

tools/testupload

@@ -1,6 +1,6
 #!/bin/sh
 
-# clean public testing/ dir and upload
-#ssh "rm -f [e-mail]:www/dist/testing/*"
-cd ~/ipython/ipython/dist
+ipdir=$PWD/..
+
+cd $ipdir/dist
 scp * [e-mail]:www/dist/testing/

IPython/Extensions/ipy_leo.py

@@ -1,660 +0,0
-""" ILeo - Leo plugin for IPython
-
-   
-"""
-import IPython.ipapi
-import IPython.genutils
-import IPython.generics
-from IPython.hooks import CommandChainDispatcher
-import re
-import UserDict
-from IPython.ipapi import TryNext 
-import IPython.macro
-import IPython.Shell
-
-_leo_push_history = set()
-
-def init_ipython(ipy):
-    """ This will be run by _ip.load('ipy_leo') 
-    
-    Leo still needs to run update_commander() after this.
-    
-    """
-    global ip
-    ip = ipy
-    IPython.Shell.hijack_tk()
-    ip.set_hook('complete_command', mb_completer, str_key = '%mb')
-    ip.expose_magic('mb',mb_f)
-    ip.expose_magic('lee',lee_f)
-    ip.expose_magic('leoref',leoref_f)
-    ip.expose_magic('lleo',lleo_f)    
-    # Note that no other push command should EVER have lower than 0
-    expose_ileo_push(push_mark_req, -1)
-    expose_ileo_push(push_cl_node,100)
-    # this should be the LAST one that will be executed, and it will never raise TryNext
-    expose_ileo_push(push_ipython_script, 1000)
-    expose_ileo_push(push_plain_python, 100)
-    expose_ileo_push(push_ev_node, 100)
-    ip.set_hook('pre_prompt_hook', ileo_pre_prompt_hook)     
-    global wb
-    wb = LeoWorkbook()
-    ip.user_ns['wb'] = wb 
-    
-
-first_launch = True
-
-def update_commander(new_leox):
-    """ Set the Leo commander to use
-    
-    This will be run every time Leo does ipython-launch; basically,
-    when the user switches the document he is focusing on, he should do
-    ipython-launch to tell ILeo what document the commands apply to.
-    
-    """
-
-    global first_launch
-    if first_launch:
-        show_welcome()
-        first_launch = False
-
-    global c,g
-    c,g = new_leox.c, new_leox.g
-    print "Set Leo Commander:",c.frame.getTitle()
-    
-    # will probably be overwritten by user, but handy for experimentation early on
-    ip.user_ns['c'] = c
-    ip.user_ns['g'] = g
-    ip.user_ns['_leo'] = new_leox
-    
-    new_leox.push = push_position_from_leo
-    run_leo_startup_node()
-
-from IPython.external.simplegeneric import generic 
-import pprint
-
-def es(s):    
-    g.es(s, tabName = 'IPython')
-    pass
-
-@generic
-def format_for_leo(obj):
-    """ Convert obj to string representiation (for editing in Leo)"""
-    return pprint.pformat(obj)
-
-# Just an example - note that this is a bad to actually do!
-#@format_for_leo.when_type(list)
-#def format_list(obj):
-#    return "\n".join(str(s) for s in obj)
-  
-
-attribute_re = re.compile('^[a-zA-Z_][a-zA-Z0-9_]*$')
-def valid_attribute(s):
-    return attribute_re.match(s)    
-
-_rootnode = None
-def rootnode():
-    """ Get ileo root node (@ipy-root) 
-    
-    if node has become invalid or has not been set, return None
-    
-    Note that the root is the *first* @ipy-root item found    
-    """
-    global _rootnode
-    if _rootnode is None:
-        return None
-    if c.positionExists(_rootnode.p):
-        return _rootnode
-    _rootnode = None
-    return None  
-
-def all_cells():
-    global _rootnode
-    d = {}
-    r = rootnode() 
-    if r is not None:
-        nodes = r.p.children_iter()
-    else:
-        nodes = c.allNodes_iter()
-
-    for p in nodes:
-        h = p.headString()
-        if h.strip() == '@ipy-root':
-            # update root node (found it for the first time)
-            _rootnode = LeoNode(p)            
-            # the next recursive call will use the children of new root
-            return all_cells()
-        
-        if h.startswith('@a '):
-            d[h.lstrip('@a ').strip()] = p.parent().copy()
-        elif not valid_attribute(h):
-            continue 
-        d[h] = p.copy()
-    return d    
-
-def eval_node(n):
-    body = n.b    
-    if not body.startswith('@cl'):
-        # plain python repr node, just eval it
-        return ip.ev(n.b)
-    # @cl nodes deserve special treatment - first eval the first line (minus cl), then use it to call the rest of body
-    first, rest = body.split('\n',1)
-    tup = first.split(None, 1)
-    # @cl alone SPECIAL USE-> dump var to user_ns
-    if len(tup) == 1:
-        val = ip.ev(rest)
-        ip.user_ns[n.h] = val
-        es("%s = %s" % (n.h, repr(val)[:20]  )) 
-        return val
-
-    cl, hd = tup 
-
-    xformer = ip.ev(hd.strip())
-    es('Transform w/ %s' % repr(xformer))
-    return xformer(rest, n)
-
-class LeoNode(object, UserDict.DictMixin):
-    """ Node in Leo outline
-    
-    Most important attributes (getters/setters available:
-     .v     - evaluate node, can also be alligned 
-     .b, .h - body string, headline string
-     .l     - value as string list
-    
-    Also supports iteration, 
-    
-    setitem / getitem (indexing):  
-     wb.foo['key'] = 12
-     assert wb.foo['key'].v == 12
-    
-    Note the asymmetry on setitem and getitem! Also other
-    dict methods are available. 
-    
-    .ipush() - run push-to-ipython
-
-    Minibuffer command access (tab completion works):
-    
-     mb save-to-file
-    
-    """
-    def __init__(self,p):
-        self.p = p.copy()
-
-    def __str__(self):
-        return "<LeoNode %s>" % str(self.p)
-    
-    __repr__ = __str__
-    
-    def __get_h(self): return self.p.headString()
-    def __set_h(self,val):
-        c.setHeadString(self.p,val)
-        LeoNode.last_edited = self
-        c.redraw()
-        
-    h = property( __get_h, __set_h, doc = "Node headline string")  
-
-    def __get_b(self): return self.p.bodyString()
-    def __set_b(self,val):
-        c.setBodyString(self.p, val)
-        LeoNode.last_edited = self
-        c.redraw()
-    
-    b = property(__get_b, __set_b, doc = "Nody body string")
-    
-    def __set_val(self, val):        
-        self.b = format_for_leo(val)
-        
-    v = property(lambda self: eval_node(self), __set_val, doc = "Node evaluated value")
-    
-    def __set_l(self,val):
-        self.b = '\n'.join(val )
-    l = property(lambda self : IPython.genutils.SList(self.b.splitlines()), 
-                 __set_l, doc = "Node value as string list")
-    
-    def __iter__(self):
-        """ Iterate through nodes direct children """
-        
-        return (LeoNode(p) for p in self.p.children_iter())
-
-    def __children(self):
-        d = {}
-        for child in self:
-            head = child.h
-            tup = head.split(None,1)
-            if len(tup) > 1 and tup[0] == '@k':
-                d[tup[1]] = child
-                continue
-            
-            if not valid_attribute(head):
-                d[head] = child
-                continue
-        return d
-    def keys(self):
-        d = self.__children()
-        return d.keys()
-    def __getitem__(self, key):
-        """ wb.foo['Some stuff'] Return a child node with headline 'Some stuff'
-        
-        If key is a valid python name (e.g. 'foo'), look for headline '@k foo' as well
-        """  
-        key = str(key)
-        d = self.__children()
-        return d[key]
-    def __setitem__(self, key, val):
-        """ You can do wb.foo['My Stuff'] = 12 to create children 
-        
-        This will create 'My Stuff' as a child of foo (if it does not exist), and 
-        do .v = 12 assignment.
-        
-        Exception:
-        
-        wb.foo['bar'] = 12
-        
-        will create a child with headline '@k bar', because bar is a valid python name
-        and we don't want to crowd the WorkBook namespace with (possibly numerous) entries
-        """
-        key = str(key)
-        d = self.__children()
-        if key in d:
-            d[key].v = val
-            return
-        
-        if not valid_attribute(key):
-            head = key
-        else:
-            head = '@k ' + key
-        p = c.createLastChildNode(self.p, head, '')
-        LeoNode(p).v = val
-        
-    def __delitem__(self, key):
-        """ Remove child
-        
-        Allows stuff like wb.foo.clear() to remove all children
-        """
-        self[key].p.doDelete()
-        c.redraw()
-    
-    def ipush(self):
-        """ Does push-to-ipython on the node """
-        push_from_leo(self)
-        
-    def go(self):
-        """ Set node as current node (to quickly see it in Outline) """
-        c.setCurrentPosition(self.p)
-        c.redraw()
-        
-    def append(self):
-        """ Add new node as the last child, return the new node """
-        p = self.p.insertAsLastChild()
-        return LeoNode(p)
-        
-        
-    def script(self):
-        """ Method to get the 'tangled' contents of the node
-        
-        (parse @others, << section >> references etc.)
-        """
-        return g.getScript(c,self.p,useSelectedText=False,useSentinels=False)
-    
-    def __get_uA(self):
-        p = self.p
-        # Create the uA if necessary.
-        if not hasattr(p.v.t,'unknownAttributes'):
-            p.v.t.unknownAttributes = {}        
-        
-        d = p.v.t.unknownAttributes.setdefault('ipython', {})
-        return d        
-    
-    uA = property(__get_uA, doc = "Access persistent unknownAttributes of node")
-        
-
-class LeoWorkbook:
-    """ class for 'advanced' node access 
-    
-    Has attributes for all "discoverable" nodes. Node is discoverable if it 
-    either
-    
-    - has a valid python name (Foo, bar_12)
-    - is a parent of an anchor node (if it has a child '@a foo', it is visible as foo)
-    
-    """
-    def __getattr__(self, key):
-        if key.startswith('_') or key == 'trait_names' or not valid_attribute(key):
-            raise AttributeError
-        cells = all_cells()
-        p = cells.get(key, None)
-        if p is None:
-            return add_var(key)
-
-        return LeoNode(p)
-
-    def __str__(self):
-        return "<LeoWorkbook>"
-    def __setattr__(self,key, val):
-        raise AttributeError("Direct assignment to workbook denied, try wb.%s.v = %s" % (key,val))
-        
-    __repr__ = __str__
-    
-    def __iter__(self):
-        """ Iterate all (even non-exposed) nodes """
-        cells = all_cells()
-        return (LeoNode(p) for p in c.allNodes_iter())
-    
-    current = property(lambda self: LeoNode(c.currentPosition()), doc = "Currently selected node")
-    
-    def match_h(self, regex):
-        cmp = re.compile(regex)
-        for node in self:
-            if re.match(cmp, node.h, re.IGNORECASE):
-                yield node
-        return
-    
-    def require(self, req):
-        """ Used to control node push dependencies 
-        
-        Call this as first statement in nodes. If node has not been pushed, it will be pushed before proceeding
-        
-        E.g. wb.require('foo') will do wb.foo.ipush() if it hasn't been done already
-        """
-        
-        if req not in _leo_push_history:
-            es('Require: ' + req)
-            getattr(self,req).ipush()
-     
-
[e-mail]_object.when_type(LeoWorkbook)
-def workbook_complete(obj, prev):
-    return all_cells().keys() + [s for s in prev if not s.startswith('_')]
-    
-
-def add_var(varname):
-    r = rootnode()
-    try:
-        if r is None:
-            p2 = g.findNodeAnywhere(c,varname)
-        else:
-            p2 = g.findNodeInChildren(c, r.p, varname)
-        if p2:
-            return LeoNode(p2)
-
-        if r is not None:
-            p2 = r.p.insertAsLastChild()
-        
-        else:
-            p2 =  c.currentPosition().insertAfter()
-        
-        c.setHeadString(p2,varname)
-        return LeoNode(p2)
-    finally:
-        c.redraw()
-
-def add_file(self,fname):
-    p2 = c.currentPosition().insertAfter()
-
-push_from_leo = CommandChainDispatcher()
-
-def expose_ileo_push(f, prio = 0):
-    push_from_leo.add(f, prio)
-
-def push_ipython_script(node):
-    """ Execute the node body in IPython, as if it was entered in interactive prompt """
-    try:
-        ohist = ip.IP.output_hist 
-        hstart = len(ip.IP.input_hist)
-        script = node.script()
-                
-        # The current node _p needs to handle wb.require() and recursive ipushes
-        old_p = ip.user_ns.get('_p',None)
-        ip.user_ns['_p'] = node
-        ip.runlines(script)
-        ip.user_ns['_p'] = old_p
-        if old_p is None:
-            del ip.user_ns['_p']
-        
-        has_output = False
-        for idx in range(hstart,len(ip.IP.input_hist)):
-            val = ohist.get(idx,None)
-            if val is None:
-                continue
-            has_output = True
-            inp = ip.IP.input_hist[idx]
-            if inp.strip():
-                es('In: %s' % (inp[:40], ))
-                
-            es('<%d> %s' % (idx, pprint.pformat(ohist[idx],width = 40)))
-        
-        if not has_output:
-            es('ipy run: %s (%d LL)' %( node.h,len(script)))
-    finally:
-        c.redraw()
-
-    
-def eval_body(body):
-    try:
-        val = ip.ev(body)
-    except:
-        # just use stringlist if it's not completely legal python expression
-        val = IPython.genutils.SList(body.splitlines())
-    return val 
-    
-def push_plain_python(node):
-    if not node.h.endswith('P'):
-        raise TryNext
-    script = node.script()
-    lines = script.count('\n')
-    try:
-        exec script in ip.user_ns
-    except:
-        print " -- Exception in script:\n"+script + "\n --"
-        raise
-    es('ipy plain: %s (%d LL)' % (node.h,lines))
-    
-
-def push_cl_node(node):
-    """ If node starts with @cl, eval it
-    
-    The result is put as last child of @ipy-results node, if it exists
-    """
-    if not node.b.startswith('@cl'):
-        raise TryNext
-        
-    p2 = g.findNodeAnywhere(c,'@ipy-results')
-    val = node.v
-    if p2:
-        es("=> @ipy-results")
-        LeoNode(p2).v = val
-    es(val)
-
-def push_ev_node(node):
-    """ If headline starts with @ev, eval it and put result in body """
-    if not node.h.startswith('@ev '):
-        raise TryNext
-    expr = node.h.lstrip('@ev ')
-    es('ipy eval ' + expr)
-    res = ip.ev(expr)
-    node.v = res
-    
-def push_mark_req(node):
-    """ This should be the first one that gets called.
-    
-    It will mark the node as 'pushed', for wb.require.
-    """
-    _leo_push_history.add(node.h)
-    raise TryNext
-    
-    
-def push_position_from_leo(p):
-    try:
-        push_from_leo(LeoNode(p))
-    except AttributeError,e:
-        if e.args == ("Commands instance has no attribute 'frame'",):
-            es("Error: ILeo not associated with .leo document")
-            es("Press alt+shift+I to fix!")
-        else:
-            raise
-
-@generic
-def edit_object_in_leo(obj, varname):
-    """ Make it @cl node so it can be pushed back directly by alt+I """
-    node = add_var(varname)
-    formatted = format_for_leo(obj)
-    if not formatted.startswith('@cl'):
-        formatted = '@cl\n' + formatted
-    node.b = formatted 
-    node.go()
-    
-@edit_object_in_leo.when_type(IPython.macro.Macro)
-def edit_macro(obj,varname):
-    bod = '_ip.defmacro("""\\\n' + obj.value + '""")'
-    node = add_var('Macro_' + varname)
-    node.b = bod
-    node.go()
-
-def get_history(hstart = 0):
-    res = []
-    ohist = ip.IP.output_hist 
-
-    for idx in range(hstart, len(ip.IP.input_hist)):
-        val = ohist.get(idx,None)
-        has_output = True
-        inp = ip.IP.input_hist_raw[idx]
-        if inp.strip():
-            res.append('In [%d]: %s' % (idx, inp))
-        if val:
-            res.append(pprint.pformat(val))
-            res.append('\n')    
-    return ''.join(res)
-    
-    
-def lee_f(self,s):
-    """ Open file(s)/objects in Leo
-    
-    - %lee hist -> open full session history in leo
-    - Takes an object. l = [1,2,"hello"]; %lee l. Alt+I in leo pushes the object back
-    - Takes an mglob pattern, e.g. '%lee *.cpp' or %lee 'rec:*.cpp'
-    - Takes input history indices:  %lee 4 6-8 10 12-47
-    """
-    import os
-        
-    try:
-        if s == 'hist':
-            wb.ipython_history.b = get_history()
-            wb.ipython_history.go()
-            return
-        
-            
-        if s and s[0].isdigit():
-            # numbers; push input slices to leo
-            lines = self.extract_input_slices(s.strip().split(), True)
-            v = add_var('stored_ipython_input')
-            v.b = '\n'.join(lines)
-            return
-            
-        
-        # try editing the object directly
-        obj = ip.user_ns.get(s, None)
-        if obj is not None:
-            edit_object_in_leo(obj,s)
-            return
-     
-        
-        # if it's not object, it's a file name / mglob pattern
-        from IPython.external import mglob
-        
-        files = (os.path.abspath(f) for f in mglob.expand(s))
-        for fname in files:
-            p = g.findNodeAnywhere(c,'@auto ' + fname)
-            if not p:
-                p = c.currentPosition().insertAfter()
-            
-            p.setHeadString('@auto ' + fname)
-            if os.path.isfile(fname):
-                c.setBodyString(p,open(fname).read())
-            c.selectPosition(p)
-        print "Editing file(s), press ctrl+shift+w in Leo to write @auto nodes"
-    finally:
-        c.redraw()
-
-def leoref_f(self,s):
-    """ Quick reference for ILeo """
-    import textwrap
-    print textwrap.dedent("""\
-    %lee file/object - open file / object in leo
-    %lleo Launch leo (use if you started ipython first!)
-    wb.foo.v  - eval node foo (i.e. headstring is 'foo' or '@ipy foo')
-    wb.foo.v = 12 - assign to body of node foo
-    wb.foo.b - read or write the body of node foo
-    wb.foo.l - body of node foo as string list
-    
-    for el in wb.foo:
-      print el.v
-       
-    """
-    )
-
-
-
-def mb_f(self, arg):
-    """ Execute leo minibuffer commands 
-    
-    Example:
-     mb save-to-file
-    """
-    c.executeMinibufferCommand(arg)
-
-def mb_completer(self,event):
-    """ Custom completer for minibuffer """
-    cmd_param = event.line.split()
-    if event.line.endswith(' '):
-        cmd_param.append('')
-    if len(cmd_param) > 2:
-        return ip.IP.Completer.file_matches(event.symbol)
-    cmds = c.commandsDict.keys()
-    cmds.sort()
-    return cmds
-
-def ileo_pre_prompt_hook(self):
-    # this will fail if leo is not running yet
-    try:
-        c.outerUpdate()
-    except NameError:
-        pass
-    raise TryNext
-    
-
-
-def show_welcome():
-    print "------------------"
-    print "Welcome to Leo-enabled IPython session!"
-    print "Try %leoref for quick reference."
-    import IPython.platutils
-    IPython.platutils.set_term_title('ILeo')
-    IPython.platutils.freeze_term_title()
-
-def run_leo_startup_node():
-    p = g.findNodeAnywhere(c,'@ipy-startup')
-    if p:
-        print "Running @ipy-startup nodes"
-        for n in LeoNode(p):
-            push_from_leo(n)
-
-def lleo_f(selg,  args):
-    """ Launch leo from within IPython
-
-    This command will return immediately when Leo has been
-    launched, leaving a Leo session that is connected 
-    with current IPython session (once you press alt+I in leo)
-
-    Usage::
-      lleo foo.leo
-      lleo 
-    """
-    
-    import shlex, sys
-    argv = ['leo'] + shlex.split(args)
-    sys.argv = argv
-    # if this var exists and is true, leo will "launch" (connect)
-    # ipython immediately when it's started
-    global _request_immediate_connect
-    _request_immediate_connect = True
-    import leo.core.runLeo
-    leo.core.runLeo.run()

IPython/kernel/core/shell.py

@@ -1,357 +0,0
-# encoding: utf-8
-# -*- test-case-name: IPython.test.test_shell -*-
-
-"""The core IPython Shell"""
-
-__docformat__ = "restructuredtext en"
-
-#-------------------------------------------------------------------------------
-#  Copyright (C) 2008  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 pprint
-import signal
-import sys
-import threading
-import time
-
-from code import InteractiveConsole, softspace
-from StringIO import StringIO
-
-from IPython.OutputTrap import OutputTrap
-from IPython import ultraTB
-
-from IPython.kernel.error import NotDefined
-
-
-class InteractiveShell(InteractiveConsole):
-    """The Basic IPython Shell class.  
-    
-    This class provides the basic capabilities of IPython.  Currently
-    this class does not do anything IPython specific.  That is, it is
-    just a python shell.
-    
-    It is modelled on code.InteractiveConsole, but adds additional
-    capabilities.  These additional capabilities are what give IPython
-    its power.  
-    
-    The current version of this class is meant to be a prototype that guides
-    the future design of the IPython core.  This class must not use Twisted
-    in any way, but it must be designed in a way that makes it easy to 
-    incorporate into Twisted and hook network protocols up to.  
-    
-    Some of the methods of this class comprise the official IPython core
-    interface.  These methods must be tread safe and they must return types
-    that can be easily serialized by protocols such as PB, XML-RPC and SOAP.
-    Locks have been provided for making the methods thread safe, but additional
-    locks can be added as needed.
-      
-    Any method that is meant to be a part of the official interface must also
-    be declared in the kernel.coreservice.ICoreService interface.  Eventually
-    all other methods should have single leading underscores to note that they
-    are not designed to be 'public.'  Currently, because this class inherits
-    from code.InteractiveConsole there are many private methods w/o leading
-    underscores.  The interface should be as simple as possible and methods 
-    should not be added to the interface unless they really need to be there.   
-    
-    Note:
-    
-    - For now I am using methods named put/get to move objects in/out of the
-      users namespace.  Originally, I was calling these methods push/pull, but
-      because code.InteractiveConsole already has a push method, I had to use
-      something different.  Eventually, we probably won't subclass this class
-      so we can call these methods whatever we want.  So, what do we want to
-      call them?
-    - We need a way of running the trapping of stdout/stderr in different ways.
-      We should be able to i) trap, ii) not trap at all or iii) trap and echo
-      things to stdout and stderr.
-    - How should errors be handled?  Should exceptions be raised?
-    - What should methods that don't compute anything return?  The default of 
-      None?
-    """
-     
-    def __init__(self, locals=None, filename="<console>"):
-        """Creates a new TrappingInteractiveConsole object."""
-        InteractiveConsole.__init__(self,locals,filename)
-        self._trap = OutputTrap(debug=0)
-        self._stdin = []
-        self._stdout = []
-        self._stderr = []
-        self._last_type = self._last_traceback = self._last_value = None
-        #self._namespace_lock = threading.Lock()
-        #self._command_lock = threading.Lock()
-        self.lastCommandIndex = -1
-        # I am using this user defined signal to interrupt the currently 
-        # running command.  I am not sure if this is the best way, but
-        # it is working!
-        # This doesn't work on Windows as it doesn't have this signal.
-        #signal.signal(signal.SIGUSR1, self._handleSIGUSR1)
-
-        # An exception handler.  Experimental: later we need to make the
-        # modes/colors available to user configuration, etc.
-        self.tbHandler = ultraTB.FormattedTB(color_scheme='NoColor',
-                                             mode='Context',
-                                             tb_offset=2)
-
-    def _handleSIGUSR1(self, signum, frame):
-        """Handle the SIGUSR1 signal by printing to stderr."""
-        print>>sys.stderr, "Command stopped."
-        
-    def _prefilter(self, line, more):
-        return line
-
-    def _trapRunlines(self, lines):
-        """
-        This executes the python source code, source, in the
-        self.locals namespace and traps stdout and stderr.  Upon
-        exiting, self.out and self.err contain the values of 
-        stdout and stderr for the last executed command only.
-        """
-        
-        # Execute the code
-        #self._namespace_lock.acquire()
-        self._trap.flush()
-        self._trap.trap()
-        self._runlines(lines)
-        self.lastCommandIndex += 1
-        self._trap.release()
-        #self._namespace_lock.release()
-                
-        # Save stdin, stdout and stderr to lists
-        #self._command_lock.acquire()
-        self._stdin.append(lines)
-        self._stdout.append(self.prune_output(self._trap.out.getvalue()))
-        self._stderr.append(self.prune_output(self._trap.err.getvalue()))
-        #self._command_lock.release()
-
-    def prune_output(self, s):
-        """Only return the first and last 1600 chars of stdout and stderr.
-        
-        Something like this is required to make sure that the engine and
-        controller don't become overwhelmed by the size of stdout/stderr.
-        """
-        if len(s) > 3200:
-            return s[:1600] + '\n............\n' + s[-1600:]
-        else: 
-            return s
-
-    # Lifted from iplib.InteractiveShell
-    def _runlines(self,lines):
-        """Run a string of one or more lines of source.
-
-        This method is capable of running a string containing multiple source
-        lines, as if they had been entered at the IPython prompt.  Since it
-        exposes IPython's processing machinery, the given strings can contain
-        magic calls (%magic), special shell access (!cmd), etc."""
-
-        # We must start with a clean buffer, in case this is run from an
-        # interactive IPython session (via a magic, for example).
-        self.resetbuffer()
-        lines = lines.split('\n')
-        more = 0
-        for line in lines:
-            # skip blank lines so we don't mess up the prompt counter, but do
-            # NOT skip even a blank line if we are in a code block (more is
-            # true)
-            if line or more:
-                more = self.push((self._prefilter(line,more)))
-                # IPython's runsource returns None if there was an error
-                # compiling the code.  This allows us to stop processing right
-                # away, so the user gets the error message at the right place.
-                if more is None:
-                    break
-        # final newline in case the input didn't have it, so that the code
-        # actually does get executed
-        if more:
-            self.push('\n')
-
-    def runcode(self, code):
-        """Execute a code object.
-
-        When an exception occurs, self.showtraceback() is called to
-        display a traceback.  All exceptions are caught except
-        SystemExit, which is reraised.
-
-        A note about KeyboardInterrupt: this exception may occur
-        elsewhere in this code, and may not always be caught.  The
-        caller should be prepared to deal with it.
-
-        """
-
-        self._last_type = self._last_traceback = self._last_value = None
-        try:
-            exec code in self.locals
-        except:
-            # Since the exception info may need to travel across the wire, we
-            # pack it in right away.  Note that we are abusing the exception
-            # value to store a fully formatted traceback, since the stack can
-            # not be serialized for network transmission.
-            et,ev,tb = sys.exc_info()
-            self._last_type = et
-            self._last_traceback = tb
-            tbinfo = self.tbHandler.text(et,ev,tb)
-            # Construct a meaningful traceback message for shipping over the
-            # wire.
-            buf = pprint.pformat(self.buffer)
-            try:
-                ename = et.__name__
-            except:
-                ename = et
-            msg = """\
-%(ev)s            
-***************************************************************************
-An exception occurred in an IPython engine while executing user code.
-
-Current execution buffer (lines being run):
-%(buf)s
-
-A full traceback from the actual engine:
-%(tbinfo)s
-***************************************************************************
-            """ % locals()
-            self._last_value = msg
-        else:
-            if softspace(sys.stdout, 0):
-                print
-
-    ##################################################################
-    # Methods that are a part of the official interface
-    #
-    # These methods should also be put in the 
-    # kernel.coreservice.ICoreService interface.
-    #
-    # These methods must conform to certain restrictions that allow
-    # them to be exposed to various network protocols:
-    #
-    # - As much as possible, these methods must return types that can be 
-    #   serialized by PB, XML-RPC and SOAP.  None is OK.
-    # - Every method must be thread safe.  There are some locks provided
-    #   for this purpose, but new, specialized locks can be added to the
-    #   class.
-    ##################################################################
-    
-    # Methods for running code
-
-    def exc_info(self):
-        """Return exception information much like sys.exc_info().
-
-        This method returns the same (etype,evalue,tb) tuple as sys.exc_info,
-        but from the last time that the engine had an exception fire."""
-
-        return self._last_type,self._last_value,self._last_traceback
-    
-    def execute(self, lines):
-        self._trapRunlines(lines)
-        if self._last_type is None:
-            return self.getCommand()
-        else:
-            raise self._last_type(self._last_value)
-        
-    # Methods for working with the namespace
-
-    def put(self, key, value):
-        """Put value into locals namespace with name key.
-        
-        I have often called this push(), but in this case the
-        InteractiveConsole class already defines a push() method that
-        is different.
-        """          
-                  
-        if not isinstance(key, str):
-            raise TypeError, "Objects must be keyed by strings."
-        self.update({key:value})
-
-    def get(self, key):
-        """Gets an item out of the self.locals dict by key.
-        
-        Raise NameError if the object doesn't exist.
-        
-        I have often called this pull().  I still like that better.
-        """
-        
-        class NotDefined(object):
-            """A class to signify an objects that is not in the users ns."""
-            pass
-        
-        if not isinstance(key, str):
-            raise TypeError, "Objects must be keyed by strings."
-        result = self.locals.get(key, NotDefined())
-        if isinstance(result, NotDefined):
-            raise NameError('name %s is not defined' % key)
-        else:
-            return result
-
-
-    def update(self, dictOfData):
-        """Loads a dict of key value pairs into the self.locals namespace."""
-        if not isinstance(dictOfData, dict):
-            raise TypeError, "update() takes a dict object."
-        #self._namespace_lock.acquire()
-        self.locals.update(dictOfData)
-        #self._namespace_lock.release()
-        
-    # Methods for getting stdout/stderr/stdin
-           
-    def reset(self):
-        """Reset the InteractiveShell."""
-        
-        #self._command_lock.acquire()        
-        self._stdin = []
-        self._stdout = []
-        self._stderr = []
-        self.lastCommandIndex = -1
-        #self._command_lock.release()
-
-        #self._namespace_lock.acquire()
-        # preserve id, mpi objects
-        mpi = self.locals.get('mpi', None)
-        id = self.locals.get('id', None)
-        del self.locals
-        self.locals = {'mpi': mpi, 'id': id}
-        #self._namespace_lock.release()
-                
-    def getCommand(self,i=None):
-        """Get the stdin/stdout/stderr of command i."""
-        
-        #self._command_lock.acquire()
-        
-        
-        if i is not None and not isinstance(i, int):
-            raise TypeError("Command index not an int: " + str(i))
-            
-        if i in range(self.lastCommandIndex + 1):
-            inResult = self._stdin[i]
-            outResult = self._stdout[i]
-            errResult = self._stderr[i]
-            cmdNum = i
-        elif i is None and self.lastCommandIndex >= 0:
-            inResult = self._stdin[self.lastCommandIndex]
-            outResult = self._stdout[self.lastCommandIndex]
-            errResult = self._stderr[self.lastCommandIndex]
-            cmdNum = self.lastCommandIndex
-        else:
-            inResult = None
-            outResult = None
-            errResult = None
-        
-        #self._command_lock.release()
-        
-        if inResult is not None:
-            return dict(commandIndex=cmdNum, stdin=inResult, stdout=outResult, stderr=errResult)
-        else:
-            raise IndexError("Command with index %s does not exist" % str(i))
-            
-    def getLastCommandIndex(self):
-        """Get the index of the last command."""
-        #self._command_lock.acquire()
-        ind = self.lastCommandIndex
-        #self._command_lock.release()
-        return ind
-

IPython/kernel/core/tests/test_shell.py

@@ -1,67 +0,0
-# encoding: utf-8
-
-"""This file contains unittests for the shell.py module."""
-
-__docformat__ = "restructuredtext en"
-
-#-------------------------------------------------------------------------------
-#  Copyright (C) 2008  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 unittest
-from IPython.kernel.core import shell
-
-resultKeys = ('commandIndex', 'stdin', 'stdout', 'stderr')
-
-class BasicShellTest(unittest.TestCase):
-
-    def setUp(self):
-        self.s = shell.InteractiveShell()
-        
-    def testExecute(self):
-        commands = [(0,"a = 5","",""),
-            (1,"b = 10","",""),
-            (2,"c = a + b","",""),
-            (3,"print c","15\n",""),
-            (4,"import math","",""),
-            (5,"2.0*math.pi","6.2831853071795862\n","")]
-        for c in commands:
-            result = self.s.execute(c[1])
-            self.assertEquals(result, dict(zip(resultKeys,c)))
-            
-    def testPutGet(self):
-        objs = [10,"hi there",1.2342354,{"p":(1,2)}]
-        for o in objs:
-            self.s.put("key",o)
-            value = self.s.get("key")
-            self.assertEquals(value,o)
-        self.assertRaises(TypeError, self.s.put,10)
-        self.assertRaises(TypeError, self.s.get,10)
-        self.s.reset()
-        self.assertRaises(NameError, self.s.get, 'a')
-        
-    def testUpdate(self):
-        d = {"a": 10, "b": 34.3434, "c": "hi there"}
-        self.s.update(d)
-        for k in d.keys():
-            value = self.s.get(k)
-            self.assertEquals(value, d[k])
-        self.assertRaises(TypeError, self.s.update, [1,2,2])
-        
-    def testCommand(self):
-        self.assertRaises(IndexError,self.s.getCommand)
-        self.s.execute("a = 5")
-        self.assertEquals(self.s.getCommand(), dict(zip(resultKeys, (0,"a = 5","",""))))
-        self.assertEquals(self.s.getCommand(0), dict(zip(resultKeys, (0,"a = 5","",""))))
-        self.s.reset()
-        self.assertEquals(self.s.getLastCommandIndex(),-1)
-        self.assertRaises(IndexError,self.s.getCommand)
-        
-        
  No newline at end of file

README_Windows.txt

@@ -1,50 +0,0
-Notes for Windows Users
-=======================
-
-See http://ipython.scipy.org/moin/IpythonOnWindows for up-to-date information
-about running IPython on Windows.
-
-
-Requirements
-------------
-
-IPython runs under (as far as the Windows family is concerned):
-
-- Windows XP, 2000 (and probably WinNT): works well.  It needs:
-
-  * PyWin32: http://sourceforge.net/projects/pywin32/
-
-  * PyReadline: http://ipython.scipy.org/moin/PyReadline/Intro
-    
-  * If you are using Python2.4, this in turn requires Tomas Heller's ctypes
-    from: http://starship.python.net/crew/theller/ctypes (not needed for Python
-    2.5 users, since 2.5 already ships with ctypes).
-
-- Windows 95/98/ME: I have no idea. It should work, but I can't test.
-
-- CygWin environments should work, they are basically Posix.
-
-It needs Python 2.3 or newer.
-
-
-Installation
-------------
-
-Double-click the supplied .exe installer file. If all goes well, that's all
-you need to do. You should now have an IPython entry in your Start Menu.
-
-
-Installation from source distribution
--------------------------------------
-
-In case the automatic installer does not work for some reason, you can
-download the ipython-XXX.tar.gz file, which contains the full IPython source
-distribution (the popular WinZip can read .tar.gz files). 
-
-After uncompressing the archive, you can install it at a command terminal just 
-like any other Python module, by using python setup.py install'. After this 
-completes, you can run the supplied win32_manual_post_install.py script which 
-will add the relevant shortcuts to your startup menu.
-
-Optionally, you may skip installation altogether and just launch "ipython.py" 
-from the root folder of the extracted source distribution.

docs/examples/core/extension.py

@@ -1,20 +0,0
-# -*- coding: utf-8 -*-
-
-import IPython.ipapi
-ip = IPython.ipapi.get()
-
-def ${name}_f(self, arg):
-    r""" Short explanation
-    
-    Long explanation, examples
-    
-    """
-    
-    # opts,args = self.parse_options(arg,'rx')
-    # if 'r' in opts: pass
-    
-    
-
-ip.expose_magic("${name}",${name}_f)        
-    
-    

docs/examples/kernel/asynctask1.py

@@ -1,32 +0,0
-#!/usr/bin/env python
-# encoding: utf-8
-
-# This example shows how the AsynTaskClient can be used
-# This example is currently broken
-
-from twisted.internet import reactor, defer
-from IPython.kernel import asyncclient
-
-mec = asyncclient.AsyncMultiEngineClient(('localhost', 10105))
-tc = asyncclient.AsyncTaskClient(('localhost',10113))
-
-cmd1 = """\
-a = 5
-b = 10*d
-c = a*b*d
-"""
-
-t1 = asyncclient.Task(cmd1, clear_before=False, clear_after=True, pull=['a','b','c'])
-
-d = mec.push(dict(d=30))
-
-def raise_and_print(tr):
-    tr.raiseException()
-    print "a, b: ", tr.ns.a, tr.ns.b
-    return tr
-
-d.addCallback(lambda _: tc.run(t1))
-d.addCallback(lambda tid: tc.get_task_result(tid,block=True))
-d.addCallback(raise_and_print)
-d.addCallback(lambda _: reactor.stop())
-reactor.run()

docs/source/install/advanced.txt

@@ -1,138 +0,0
-=========================================
-Advanced installation options for IPython
-=========================================
-
-.. contents::
-
-Introduction
-============
-
-IPython enables parallel applications to be developed in Python. This document
-describes the steps required to install IPython. For an overview of IPython's
-architecture as it relates to parallel computing, see our :ref:`introduction to
-parallel computing with IPython <ip1par>`.
-
-Please let us know if you have problems installing IPython or any of its
-dependencies. We have tested IPython extensively with Python 2.4 and 2.5.
-
-.. warning::
-
-	IPython will not work with Python 2.3 or below.
-
-IPython has three required dependencies:
-
-	1. `IPython`__
-	2. `Zope Interface`__
-	3. `Twisted`__
-	4. `Foolscap`__
-
-.. __: http://ipython.scipy.org
-.. __: http://pypi.python.org/pypi/zope.interface
-.. __: http://twistedmatrix.com
-.. __: http://foolscap.lothar.com/trac
-
-It also has the following optional dependencies:
-
-	1. pexpect (used for certain tests)
-	2. nose (used to run our test suite)
-	3. sqlalchemy (used for database support)
-	4. mpi4py (for MPI support)
-	5. Sphinx and pygments (for building documentation)
-	6. pyOpenSSL (for security)
-
-Getting IPython
-================
-
-IPython development has been moved to `Launchpad`_.  The development branch of IPython can be checkout out using `Bazaar`_::
-
-    $ bzr branch lp:///~ipython/ipython/ipython1-dev
-
-.. _Launchpad: http://www.launchpad.net/ipython
-.. _Bazaar: http://bazaar-vcs.org/
-
-Installation using setuptools
-=============================
-
-The easiest way of installing IPython and its dependencies is using
-`setuptools`_. If you have setuptools installed you can simple use the ``easy_install``
-script that comes with setuptools (this should be on your path if you have setuptools)::
-
-	$ easy_install ipython1
-
-This will download and install the latest version of IPython as well as all of its dependencies.  For this to work, you will need to be connected to the internet when you run this command. This will install everything info the ``site-packages`` directory of your Python distribution. If this is the system wide Python, you will likely need admin privileges. For information about installing Python packages to other locations (that don't require admin privileges) see the `setuptools`_ documentation.
-
-.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
-
-If you don't want `setuptools`_ to automatically install the dependencies, you can also get the dependencies yourself, using ``easy_install``::
-
-	$ easy_install IPython
-	$ easy_install zope.interface
-	$ easy_install Twisted
-	$ easy_install foolscap
-
-or by simply downloading and installing the dependencies manually.
-
-If you want to have secure (highly recommended) network connections, you will also
-need to get `pyOpenSSL`__, version 0.6, or just do:
-
-	$ easy_install ipython1[security]
-
-.. hint::	If you want to do development on IPython and want to always 
-   run off your development branch, you can run 
-   :command:`python setupegg.py develop` in the IPython source tree.
-
-.. __: http://pyopenssl.sourceforge.net/
-
-Installation using plain distutils
-==================================
-
-If you don't have `setuptools`_ installed or don't want to use it, you can also install IPython and its dependencies using ``distutils``.  In this approach, you will need to get the most recent stable releases of IPython's dependencies and install each of them by doing::
-
-	$ python setup.py install
-
-The dependencies need to be installed before installing IPython.  After installing the dependencies, install IPython by running::
-
-	$ cd ipython1-dev
-	$ python setup.py install
-
-.. note:: Here we are using setup.py rather than setupegg.py.
-
-.. _install_testing:
-
-Testing
-=======
-
-Once you have completed the installation of the IPython kernel you can run our test suite
-with the command::
-
-	trial ipython1
-	
-Or if you have `nose`__ installed::
-
-	nosetests -v ipython1
-	
-The ``trial`` command is part of Twisted and allows asynchronous network based
-applications to be tested using Python's unittest framework. Please let us know
-if the tests do not pass. The best way to get in touch with us is on the `IPython
-developer mailing list`_.
-
-.. __: http://somethingaboutorange.com/mrl/projects/nose/
-.. _IPython developer mailing list: http://projects.scipy.org/mailman/listinfo/ipython-dev
-
-MPI Support
-===========
-
-IPython includes optional support for the Message Passing Interface (`MPI`_),
-which enables the IPython Engines to pass data between each other using `MPI`_.  To use MPI with IPython, the minimal requirements are:
-
-	* An MPI implementation (we recommend `Open MPI`_)
-	* A way to call MPI (we recommend `mpi4py`_)
-
-But, IPython should work with any MPI implementation and with any code
-(Python/C/C++/Fortran) that uses MPI. Please contact us for more information about
-this.
-
-.. _MPI: http://www-unix.mcs.anl.gov/mpi/
-.. _mpi4py: http://mpi4py.scipy.org/
-.. _Open MPI: http://www.open-mpi.org/
-

docs/source/install/basic.txt

@@ -1,272 +0,0
-=============================
-Basic installation of IPython
-=============================
-
-Installation
-============
-
-Instant instructions
---------------------
-
-If you are of the impatient kind, under Linux/Unix simply untar/unzip
-the download, then install with 'python setup.py install'. Under
-Windows, double-click on the provided .exe binary installer.
-
-Then, take a look at Customization_ section for configuring things
-optimally and `Quick tips`_ for quick tips on efficient use of
-IPython. You can later refer to the rest of the manual for all the
-gory details.
-
-See the notes in upgrading_ section for upgrading IPython versions.
-
-
-    Detailed Unix instructions (Linux, Mac OS X, etc.)
-
-For RPM based systems, simply install the supplied package in the usual
-manner. If you download the tar archive, the process is:
-
-   1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is
-      the version number). It will make a directory called ipython-XXX.
-      Change into that directory where you will find the files README
-      and setup.py. Once you've completed the installation, you can
-      safely remove this directory.
-   2. If you are installing over a previous installation of version
-      0.2.0 or earlier, first remove your $HOME/.ipython directory,
-      since the configuration file format has changed somewhat (the '='
-      were removed from all option specifications). Or you can call
-      ipython with the -upgrade option and it will do this automatically
-      for you.
-   3. IPython uses distutils, so you can install it by simply typing at
-      the system prompt (don't type the $)::
-      
-      	$ python setup.py install
-      	
-      Note that this assumes you have root access to your machine. If
-      you don't have root access or don't want IPython to go in the
-      default python directories, you'll need to use the ``--home`` option
-      (or ``--prefix``). For example::
-      
-      	$ python setup.py install --home $HOME/local
-      	
-      will install IPython into $HOME/local and its subdirectories
-      (creating them if necessary).
-      You can type::
-      
-      	$ python setup.py --help
-      	
-      for more details.
-      
-      Note that if you change the default location for ``--home`` at
-      installation, IPython may end up installed at a location which is
-      not part of your $PYTHONPATH environment variable. In this case,
-      you'll need to configure this variable to include the actual
-      directory where the IPython/ directory ended (typically the value
-      you give to ``--home`` plus /lib/python).
-
-
-Mac OSX information
--------------------
-
-Under OSX, there is a choice you need to make. Apple ships its own build
-of Python, which lives in the core OSX filesystem hierarchy. You can
-also manually install a separate Python, either purely by hand
-(typically in /usr/local) or by using Fink, which puts everything under
-/sw. Which route to follow is a matter of personal preference, as I've
-seen users who favor each of the approaches. Here I will simply list the
-known installation issues under OSX, along with their solutions.
-
-This page: http://geosci.uchicago.edu/~tobis/pylab.html contains
-information on this topic, with additional details on how to make
-IPython and matplotlib play nicely under OSX.
-
-To run IPython and readline on OSX "Leopard" system python, see the 
-wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard
-
-
-GUI problems
-------------
-
-The following instructions apply to an install of IPython under OSX from
-unpacking the .tar.gz distribution and installing it for the default
-Python interpreter shipped by Apple. If you are using a fink install,
-fink will take care of these details for you, by installing IPython
-against fink's Python.
-
-IPython offers various forms of support for interacting with graphical
-applications from the command line, from simple Tk apps (which are in
-principle always supported by Python) to interactive control of WX, Qt
-and GTK apps. Under OSX, however, this requires that ipython is
-installed by calling the special pythonw script at installation time,
-which takes care of coordinating things with Apple's graphical environment.
-
-So when installing under OSX, it is best to use the following command:: 
-
-	$ sudo pythonw setup.py install --install-scripts=/usr/local/bin
-
-or
-
-	$ sudo pythonw setup.py install --install-scripts=/usr/bin
-	
-depending on where you like to keep hand-installed executables.
-
-The resulting script will have an appropriate shebang line (the first
-line in the script whic begins with #!...) such that the ipython
-interpreter can interact with the OS X GUI. If the installed version
-does not work and has a shebang line that points to, for example, just
-/usr/bin/python, then you might have a stale, cached version in your
-build/scripts-<python-version> directory. Delete that directory and
-rerun the setup.py.
-
-It is also a good idea to use the special flag ``--install-scripts`` as
-indicated above, to ensure that the ipython scripts end up in a location
-which is part of your $PATH. Otherwise Apple's Python will put the
-scripts in an internal directory not available by default at the command
-line (if you use /usr/local/bin, you need to make sure this is in your
-$PATH, which may not be true by default).
-
-
-Readline problems
------------------
-
-By default, the Python version shipped by Apple does not include the
-readline library, so central to IPython's behavior. If you install
-IPython against Apple's Python, you will not have arrow keys, tab
-completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt
-readline library here:
-http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip
-
-If you are using OSX 10.4 (Tiger), after installing this package you
-need to either:
-
-   1. move readline.so from /Library/Python/2.3 to
-      /Library/Python/2.3/site-packages, or
-   2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip
-
-Users installing against Fink's Python or a properly hand-built one
-should not have this problem.
-
-
-DarwinPorts
------------
-
-I report here a message from an OSX user, who suggests an alternative
-means of using IPython under this operating system with good results.
-Please let me know of any updates that may be useful for this section.
-His message is reproduced verbatim below:
-
-    From: Markus Banfi <markus.banfi-AT-mospheira.net> 
-
-    As a MacOS X (10.4.2) user I prefer to install software using
-    DawinPorts instead of Fink. I had no problems installing ipython
-    with DarwinPorts. It's just: 
-
-    sudo port install py-ipython 
-
-    It automatically resolved all dependencies (python24, readline,
-    py-readline). So far I did not encounter any problems with the
-    DarwinPorts port of ipython. 
-
-
-
-Windows instructions
---------------------
-
-Some of IPython's very useful features are:
-
-    * Integrated readline support (Tab-based file, object and attribute
-      completion, input history across sessions, editable command line,
-      etc.)
-    * Coloring of prompts, code and tracebacks.
-
-.. _pyreadline:
-
-These, by default, are only available under Unix-like operating systems.
-However, thanks to Gary Bishop's work, Windows XP/2k users can also
-benefit from them. His readline library originally implemented both GNU
-readline functionality and color support, so that IPython under Windows
-XP/2k can be as friendly and powerful as under Unix-like environments.
-
-This library, now named PyReadline, has been absorbed by the IPython
-team (Jörgen Stenarson, in particular), and it continues to be developed
-with new features, as well as being distributed directly from the
-IPython site.
-
-The PyReadline extension requires CTypes and the windows IPython
-installer needs PyWin32, so in all you need:
-
-   1. PyWin32 from http://sourceforge.net/projects/pywin32.
-   2. PyReadline for Windows from
-      http://ipython.scipy.org/moin/PyReadline/Intro. That page contains
-      further details on using and configuring the system to your liking.
-   3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes
-      from http://starship.python.net/crew/theller/ctypes(you must use
-      version 0.9.1 or newer). This package is included in Python 2.5,
-      so you don't need to manually get it if your Python version is 2.5
-      or newer.
-
-Warning about a broken readline-like library: several users have
-reported problems stemming from using the pseudo-readline library at
-http://newcenturycomputers.net/projects/readline.html. This is a broken
-library which, while called readline, only implements an incomplete
-subset of the readline API. Since it is still called readline, it fools
-IPython's detection mechanisms and causes unpredictable crashes later.
-If you wish to use IPython under Windows, you must NOT use this library,
-which for all purposes is (at least as of version 1.6) terminally broken.
-
-
-Installation procedure
-----------------------
-
-Once you have the above installed, from the IPython download directory
-grab the ipython-XXX.win32.exe file, where XXX represents the version
-number. This is a regular windows executable installer, which you can
-simply double-click to install. It will add an entry for IPython to your
-Start Menu, as well as registering IPython in the Windows list of
-applications, so you can later uninstall it from the Control Panel.
-
-IPython tries to install the configuration information in a directory
-named .ipython (_ipython under Windows) located in your 'home'
-directory. IPython sets this directory by looking for a HOME environment
-variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH
-(these are always defined by Windows). This typically gives something
-like C:\Documents and Settings\YourUserName, but your local details may
-vary. In this directory you will find all the files that configure
-IPython's defaults, and you can put there your profiles and extensions.
-This directory is automatically added by IPython to sys.path, so
-anything you place there can be found by import statements.
-
-
-Upgrading
----------
-
-For an IPython upgrade, you should first uninstall the previous version.
-This will ensure that all files and directories (such as the
-documentation) which carry embedded version strings in their names are
-properly removed.
-
-
-Manual installation under Win32
--------------------------------
-
-In case the automatic installer does not work for some reason, you can
-download the ipython-XXX.tar.gz file, which contains the full IPython
-source distribution (the popular WinZip can read .tar.gz files). After
-uncompressing the archive, you can install it at a command terminal just
-like any other Python module, by using 'python setup.py install'.
-
-After the installation, run the supplied win32_manual_post_install.py
-script, which creates the necessary Start Menu shortcuts for you.
-
-
-.. upgrading:
-
-Upgrading from a previous version
----------------------------------
-
-If you are upgrading from a previous version of IPython, you may want
-to upgrade the contents of your ~/.ipython directory. Just run
-%upgrade, look at the diffs and delete the suggested files manually,
-if you think you can lose the old versions. %upgrade will never
-overwrite or delete anything.
-
-

win32_manual_post_install.py

@@ -1,141 +0,0
-#!python
-"""Windows-specific part of the installation"""
-
-import os, sys
-
-try:
-    import shutil,pythoncom
-    from win32com.shell import shell
-    import _winreg as wreg
-except ImportError:
-    print """
-You seem to be missing the PythonWin extensions necessary for automatic
-installation.  You can get them (free) from
-http://starship.python.net/crew/mhammond/
-
-Please see the manual for details if you want to finish the installation by
-hand, or get PythonWin and repeat the procedure.
-
-Press <Enter> to exit this installer."""
-    raw_input()
-    sys.exit()
-
-
-def make_shortcut(fname,target,args='',start_in='',comment='',icon=None):
-    """Make a Windows shortcut (.lnk) file.
-
-    make_shortcut(fname,target,args='',start_in='',comment='',icon=None)
-
-    Arguments:
-        fname - name of the final shortcut file (include the .lnk)
-        target - what the shortcut will point to
-        args - additional arguments to pass to the target program
-        start_in - directory where the target command will be called
-        comment - for the popup tooltips
-        icon - optional icon file. This must be a tuple of the type 
-        (icon_file,index), where index is the index of the icon you want
-        in the file. For single .ico files, index=0, but for icon libraries
-        contained in a single file it can be >0.
-    """
-
-    shortcut = pythoncom.CoCreateInstance(
-        shell.CLSID_ShellLink, None,
-        pythoncom.CLSCTX_INPROC_SERVER, shell.IID_IShellLink
-    )
-    shortcut.SetPath(target)
-    shortcut.SetArguments(args)
-    shortcut.SetWorkingDirectory(start_in)
-    shortcut.SetDescription(comment)
-    if icon:
-        shortcut.SetIconLocation(*icon)
-    shortcut.QueryInterface(pythoncom.IID_IPersistFile).Save(fname,0)
-
-
-def run(wait=0):
-    # Find where the Start Menu and My Documents are on the filesystem
-    key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
-                       r'Software\Microsoft\Windows\CurrentVersion'
-                       r'\Explorer\Shell Folders')
-
-    programs_dir = wreg.QueryValueEx(key,'Programs')[0]
-    my_documents_dir = wreg.QueryValueEx(key,'Personal')[0]
-    key.Close()
-
-    # Find where the 'program files' directory is
-    key = wreg.OpenKey(wreg.HKEY_LOCAL_MACHINE,
-                       r'SOFTWARE\Microsoft\Windows\CurrentVersion')
-
-    program_files_dir = wreg.QueryValueEx(key,'ProgramFilesDir')[0]
-    key.Close()
-
-
-    # File and directory names
-    ip_dir = program_files_dir + r'\IPython'
-    ip_prog_dir = programs_dir + r'\IPython'
-    doc_dir = ip_dir+r'\doc'
-    ip_filename = ip_dir+r'\IPython_shell.py'
-    pycon_icon = doc_dir+r'\pycon.ico'
-
-    if not os.path.isdir(ip_dir):
-        os.mkdir(ip_dir)
-
-    # Copy startup script and documentation
-    shutil.copy(sys.prefix+r'\Scripts\ipython',ip_filename)
-    if os.path.isdir(doc_dir):
-        shutil.rmtree(doc_dir)
-    shutil.copytree('doc',doc_dir)
-
-    # make shortcuts for IPython, html and pdf docs.
-    print 'Making entries for IPython in Start Menu...',
-
-    # Create .bat file in \Scripts
-    fic = open(sys.prefix + r'\Scripts\ipython.bat','w')
-    fic.write('"' + sys.prefix + r'\python.exe' + '" -i ' + '"' +
-              sys.prefix + r'\Scripts\ipython" %*')
-    fic.close()
-
-    # Create .bat file in \\Scripts
-    fic = open(sys.prefix + '\\Scripts\\ipython.bat','w')
-    fic.write('"' + sys.prefix + '\\python.exe' + '" -i ' + '"' + sys.prefix + '\\Scripts\ipython" %*')
-    fic.close()
-
-    # Create shortcuts in Programs\IPython:
-    if not os.path.isdir(ip_prog_dir):
-        os.mkdir(ip_prog_dir)
-    os.chdir(ip_prog_dir)
-
-    man_pdf = doc_dir + r'\manual\ipython.pdf'
-    man_htm = doc_dir + r'\manual\ipython.html'
-
-    make_shortcut('IPython.lnk',sys.executable, '"%s"' % ip_filename,
-                  my_documents_dir,
-                  'IPython - Enhanced python command line interpreter',
-                  (pycon_icon,0))
-    make_shortcut('pysh.lnk',sys.executable, '"%s" -p pysh' % ip_filename,
-                  my_documents_dir,
-                  'pysh - a system shell with Python syntax (IPython based)',
-                  (pycon_icon,0))
-    make_shortcut('Manual in HTML format.lnk',man_htm,'','',
-                  'IPython Manual - HTML format')
-    make_shortcut('Manual in PDF format.lnk',man_pdf,'','',
-                  'IPython Manual - PDF format')
-
-    print """Done.
-
-I created the directory %s. There you will find the
-IPython startup script and manuals.
-
-An IPython menu was also created in your Start Menu, with entries for
-IPython itself and the manual in HTML and PDF formats.
-
-For reading PDF documents you need the freely available Adobe Acrobat
-Reader. If you don't have it, you can download it from:
-http://www.adobe.com/products/acrobat/readstep2.html
-""" % ip_dir
-
-    if wait:
-        print "Finished with IPython installation. Press Enter to exit this installer.",
-        raw_input()
-
-if __name__ == '__main__':
-    run()