Miscellaneous docs fixes

IPython/core/debugger.py

@@ -1,566 +1,566 b''
 # -*- coding: utf-8 -*-
 """
 Pdb debugger class.
 
 Modified from the standard pdb.Pdb class to avoid including readline, so that
 the command line completion of other programs which include this isn't
 damaged.
 
 In the future, this class will be expanded with improvements over the standard
 pdb.
 
 The code in this file is mainly lifted out of cmd.py in Python 2.2, with minor
 changes. Licensing should therefore be under the standard Python terms.  For
 details on the PSF (Python Software Foundation) standard license, see:
 
 http://www.python.org/2.2.3/license.html"""
 
 #*****************************************************************************
 #
 #       This file is licensed under the PSF license.
 #
 #       Copyright (C) 2001 Python Software Foundation, www.python.org
 #       Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
 #
 #
 #*****************************************************************************
 from __future__ import print_function
 
 import bdb
 import functools
 import linecache
 import sys
 
 from IPython.utils import PyColorize, ulinecache
 from IPython.core import ipapi
 from IPython.utils import coloransi, io, openpy, py3compat
 from IPython.core.excolors import exception_colors
 
 # See if we can use pydb.
 has_pydb = False
 prompt = 'ipdb> '
 #We have to check this directly from sys.argv, config struct not yet available
 if '--pydb' in sys.argv:
     try:
         import pydb
         if hasattr(pydb.pydb, "runl") and pydb.version>'1.17':
             # Version 1.17 is broken, and that's what ships with Ubuntu Edgy, so we
             # better protect against it.
             has_pydb = True
     except ImportError:
         print("Pydb (http://bashdb.sourceforge.net/pydb/) does not seem to be available")
 
 if has_pydb:
     from pydb import Pdb as OldPdb
     #print "Using pydb for %run -d and post-mortem" #dbg
     prompt = 'ipydb> '
 else:
     from pdb import Pdb as OldPdb
 
 # Allow the set_trace code to operate outside of an ipython instance, even if
 # it does so with some limitations.  The rest of this support is implemented in
 # the Tracer constructor.
 def BdbQuit_excepthook(et, ev, tb, excepthook=None):
     """Exception hook which handles `BdbQuit` exceptions.
 
     All other exceptions are processed using the `excepthook`
     parameter.
     """
     if et==bdb.BdbQuit:
         print('Exiting Debugger.')
     elif excepthook is not None:
         excepthook(et, ev, tb)
     else:
         # Backwards compatibility. Raise deprecation warning?
         BdbQuit_excepthook.excepthook_ori(et,ev,tb)
 
 def BdbQuit_IPython_excepthook(self,et,ev,tb,tb_offset=None):
     print('Exiting Debugger.')
 
 
 class Tracer(object):
     """Class for local debugging, similar to pdb.set_trace.
 
     Instances of this class, when called, behave like pdb.set_trace, but
     providing IPython's enhanced capabilities.
 
     This is implemented as a class which must be initialized in your own code
     and not as a standalone function because we need to detect at runtime
     whether IPython is already active or not.  That detection is done in the
     constructor, ensuring that this code plays nicely with a running IPython,
     while functioning acceptably (though with limitations) if outside of it.
     """
 
     def __init__(self,colors=None):
         """Create a local debugger instance.
 
         :Parameters:
 
           - `colors` (None): a string containing the name of the color scheme to
         use, it must be one of IPython's valid color schemes.  If not given, the
         function will default to the current IPython scheme when running inside
         IPython, and to 'NoColor' otherwise.
 
         Usage example:
 
         from IPython.core.debugger import Tracer; debug_here = Tracer()
 
         ... later in your code
         debug_here()  # -> will open up the debugger at that point.
 
         Once the debugger activates, you can use all of its regular commands to
         step through code, set breakpoints, etc.  See the pdb documentation
         from the Python standard library for usage details.
         """
 
         try:
             ip = get_ipython()
         except NameError:
             # Outside of ipython, we set our own exception hook manually
             sys.excepthook = functools.partial(BdbQuit_excepthook,
                                                excepthook=sys.excepthook)
             def_colors = 'NoColor'
             try:
                 # Limited tab completion support
                 import readline
                 readline.parse_and_bind('tab: complete')
             except ImportError:
                 pass
         else:
             # In ipython, we use its custom exception handler mechanism
             def_colors = ip.colors
             ip.set_custom_exc((bdb.BdbQuit,), BdbQuit_IPython_excepthook)
 
         if colors is None:
             colors = def_colors
 
         # The stdlib debugger internally uses a modified repr from the `repr`
         # module, that limits the length of printed strings to a hardcoded
         # limit of 30 characters.  That much trimming is too aggressive, let's
         # at least raise that limit to 80 chars, which should be enough for
         # most interactive uses.
         try:
             from repr import aRepr
             aRepr.maxstring = 80
         except:
             # This is only a user-facing convenience, so any error we encounter
             # here can be warned about but can be otherwise ignored.  These
             # printouts will tell us about problems if this API changes
             import traceback
             traceback.print_exc()
 
         self.debugger = Pdb(colors)
 
     def __call__(self):
         """Starts an interactive debugger at the point where called.
 
         This is similar to the pdb.set_trace() function from the std lib, but
         using IPython's enhanced debugger."""
 
         self.debugger.set_trace(sys._getframe().f_back)
 
 
 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
     """Make new_fn have old_fn's doc string. This is particularly useful
-    for the do_... commands that hook into the help system.
+    for the ``do_...`` commands that hook into the help system.
     Adapted from from a comp.lang.python posting
     by Duncan Booth."""
     def wrapper(*args, **kw):
         return new_fn(*args, **kw)
     if old_fn.__doc__:
         wrapper.__doc__ = old_fn.__doc__ + additional_text
     return wrapper
 
 
 def _file_lines(fname):
     """Return the contents of a named file as a list of lines.
 
     This function never raises an IOError exception: if the file can't be
     read, it simply returns an empty list."""
 
     try:
         outfile = open(fname)
     except IOError:
         return []
     else:
         out = outfile.readlines()
         outfile.close()
         return out
 
 
 class Pdb(OldPdb):
     """Modified Pdb class, does not load readline."""
 
     def __init__(self,color_scheme='NoColor',completekey=None,
                  stdin=None, stdout=None):
 
         # Parent constructor:
         if has_pydb and completekey is None:
             OldPdb.__init__(self,stdin=stdin,stdout=io.stdout)
         else:
             OldPdb.__init__(self,completekey,stdin,stdout)
 
         self.prompt = prompt # The default prompt is '(Pdb)'
 
         # IPython changes...
         self.is_pydb = has_pydb
 
         self.shell = ipapi.get()
 
         if self.is_pydb:
 
             # interactiveshell.py's ipalias seems to want pdb's checkline
             # which located in pydb.fn
             import pydb.fns
             self.checkline = lambda filename, lineno: \
                              pydb.fns.checkline(self, filename, lineno)
 
             self.curframe = None
             self.do_restart = self.new_do_restart
 
             self.old_all_completions = self.shell.Completer.all_completions
             self.shell.Completer.all_completions=self.all_completions
 
             self.do_list = decorate_fn_with_doc(self.list_command_pydb,
                                                 OldPdb.do_list)
             self.do_l     = self.do_list
             self.do_frame = decorate_fn_with_doc(self.new_do_frame,
                                                  OldPdb.do_frame)
 
         self.aliases = {}
 
         # Create color table: we copy the default one from the traceback
         # module and add a few attributes needed for debugging
         self.color_scheme_table = exception_colors()
 
         # shorthands
         C = coloransi.TermColors
         cst = self.color_scheme_table
 
         cst['NoColor'].colors.breakpoint_enabled = C.NoColor
         cst['NoColor'].colors.breakpoint_disabled = C.NoColor
 
         cst['Linux'].colors.breakpoint_enabled = C.LightRed
         cst['Linux'].colors.breakpoint_disabled = C.Red
 
         cst['LightBG'].colors.breakpoint_enabled = C.LightRed
         cst['LightBG'].colors.breakpoint_disabled = C.Red
 
         self.set_colors(color_scheme)
 
         # Add a python parser so we can syntax highlight source while
         # debugging.
         self.parser = PyColorize.Parser()
 
     def set_colors(self, scheme):
         """Shorthand access to the color table scheme selector method."""
         self.color_scheme_table.set_active_scheme(scheme)
 
     def interaction(self, frame, traceback):
         self.shell.set_completer_frame(frame)
         OldPdb.interaction(self, frame, traceback)
 
     def new_do_up(self, arg):
         OldPdb.do_up(self, arg)
         self.shell.set_completer_frame(self.curframe)
     do_u = do_up = decorate_fn_with_doc(new_do_up, OldPdb.do_up)
 
     def new_do_down(self, arg):
         OldPdb.do_down(self, arg)
         self.shell.set_completer_frame(self.curframe)
 
     do_d = do_down = decorate_fn_with_doc(new_do_down, OldPdb.do_down)
 
     def new_do_frame(self, arg):
         OldPdb.do_frame(self, arg)
         self.shell.set_completer_frame(self.curframe)
 
     def new_do_quit(self, arg):
 
         if hasattr(self, 'old_all_completions'):
             self.shell.Completer.all_completions=self.old_all_completions
 
 
         return OldPdb.do_quit(self, arg)
 
     do_q = do_quit = decorate_fn_with_doc(new_do_quit, OldPdb.do_quit)
 
     def new_do_restart(self, arg):
         """Restart command. In the context of ipython this is exactly the same
         thing as 'quit'."""
         self.msg("Restart doesn't make sense here. Using 'quit' instead.")
         return self.do_quit(arg)
 
     def postloop(self):
         self.shell.set_completer_frame(None)
 
     def print_stack_trace(self):
         try:
             for frame_lineno in self.stack:
                 self.print_stack_entry(frame_lineno, context = 5)
         except KeyboardInterrupt:
             pass
 
     def print_stack_entry(self,frame_lineno,prompt_prefix='\n-> ',
                           context = 3):
         #frame, lineno = frame_lineno
         print(self.format_stack_entry(frame_lineno, '', context), file=io.stdout)
 
         # vds: >>
         frame, lineno = frame_lineno
         filename = frame.f_code.co_filename
         self.shell.hooks.synchronize_with_editor(filename, lineno, 0)
         # vds: <<
 
     def format_stack_entry(self, frame_lineno, lprefix=': ', context = 3):
         import repr
 
         ret = []
 
         Colors = self.color_scheme_table.active_colors
         ColorsNormal = Colors.Normal
         tpl_link = u'%s%%s%s' % (Colors.filenameEm, ColorsNormal)
         tpl_call = u'%s%%s%s%%s%s' % (Colors.vName, Colors.valEm, ColorsNormal)
         tpl_line = u'%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
         tpl_line_em = u'%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line,
                                             ColorsNormal)
 
         frame, lineno = frame_lineno
 
         return_value = ''
         if '__return__' in frame.f_locals:
             rv = frame.f_locals['__return__']
             #return_value += '->'
             return_value += repr.repr(rv) + '\n'
         ret.append(return_value)
 
         #s = filename + '(' + `lineno` + ')'
         filename = self.canonic(frame.f_code.co_filename)
         link = tpl_link % py3compat.cast_unicode(filename)
 
         if frame.f_code.co_name:
             func = frame.f_code.co_name
         else:
             func = "<lambda>"
 
         call = ''
         if func != '?':
             if '__args__' in frame.f_locals:
                 args = repr.repr(frame.f_locals['__args__'])
             else:
                 args = '()'
             call = tpl_call % (func, args)
 
         # The level info should be generated in the same format pdb uses, to
         # avoid breaking the pdbtrack functionality of python-mode in *emacs.
         if frame is self.curframe:
             ret.append('> ')
         else:
             ret.append('  ')
         ret.append(u'%s(%s)%s\n' % (link,lineno,call))
 
         start = lineno - 1 - context//2
         lines = ulinecache.getlines(filename)
         start = min(start, len(lines) - context)
         start = max(start, 0)
         lines = lines[start : start + context]
 
         for i,line in enumerate(lines):
             show_arrow = (start + 1 + i == lineno)
             linetpl = (frame is self.curframe or show_arrow) \
                       and tpl_line_em \
                       or tpl_line
             ret.append(self.__format_line(linetpl, filename,
                                           start + 1 + i, line,
                                           arrow = show_arrow) )
         return ''.join(ret)
 
     def __format_line(self, tpl_line, filename, lineno, line, arrow = False):
         bp_mark = ""
         bp_mark_color = ""
 
         scheme = self.color_scheme_table.active_scheme_name
         new_line, err = self.parser.format2(line, 'str', scheme)
         if not err: line = new_line
 
         bp = None
         if lineno in self.get_file_breaks(filename):
             bps = self.get_breaks(filename, lineno)
             bp = bps[-1]
 
         if bp:
             Colors = self.color_scheme_table.active_colors
             bp_mark = str(bp.number)
             bp_mark_color = Colors.breakpoint_enabled
             if not bp.enabled:
                 bp_mark_color = Colors.breakpoint_disabled
 
         numbers_width = 7
         if arrow:
             # This is the line with the error
             pad = numbers_width - len(str(lineno)) - len(bp_mark)
             if pad >= 3:
                 marker = '-'*(pad-3) + '-> '
             elif pad == 2:
                  marker = '> '
             elif pad == 1:
                  marker = '>'
             else:
                  marker = ''
             num = '%s%s' % (marker, str(lineno))
             line = tpl_line % (bp_mark_color + bp_mark, num, line)
         else:
             num = '%*s' % (numbers_width - len(bp_mark), str(lineno))
             line = tpl_line % (bp_mark_color + bp_mark, num, line)
 
         return line
 
     def list_command_pydb(self, arg):
         """List command to use if we have a newer pydb installed"""
         filename, first, last = OldPdb.parse_list_cmd(self, arg)
         if filename is not None:
             self.print_list_lines(filename, first, last)
 
     def print_list_lines(self, filename, first, last):
         """The printing (as opposed to the parsing part of a 'list'
         command."""
         try:
             Colors = self.color_scheme_table.active_colors
             ColorsNormal = Colors.Normal
             tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
             tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line, ColorsNormal)
             src = []
             if filename == "<string>" and hasattr(self, "_exec_filename"):
                 filename = self._exec_filename
 
             for lineno in range(first, last+1):
                 line = ulinecache.getline(filename, lineno)
                 if not line:
                     break
 
                 if lineno == self.curframe.f_lineno:
                     line = self.__format_line(tpl_line_em, filename, lineno, line, arrow = True)
                 else:
                     line = self.__format_line(tpl_line, filename, lineno, line, arrow = False)
 
                 src.append(line)
                 self.lineno = lineno
 
             print(''.join(src), file=io.stdout)
 
         except KeyboardInterrupt:
             pass
 
     def do_list(self, arg):
         self.lastcmd = 'list'
         last = None
         if arg:
             try:
                 x = eval(arg, {}, {})
                 if type(x) == type(()):
                     first, last = x
                     first = int(first)
                     last = int(last)
                     if last < first:
                         # Assume it's a count
                         last = first + last
                 else:
                     first = max(1, int(x) - 5)
             except:
                 print('*** Error in argument:', repr(arg))
                 return
         elif self.lineno is None:
             first = max(1, self.curframe.f_lineno - 5)
         else:
             first = self.lineno + 1
         if last is None:
             last = first + 10
         self.print_list_lines(self.curframe.f_code.co_filename, first, last)
 
         # vds: >>
         lineno = first
         filename = self.curframe.f_code.co_filename
         self.shell.hooks.synchronize_with_editor(filename, lineno, 0)
         # vds: <<
 
     do_l = do_list
 
     def do_pdef(self, arg):
         """Print the call signature for any callable object.
 
         The debugger interface to %pdef"""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('pdef')(arg, namespaces=namespaces)
 
     def do_pdoc(self, arg):
         """Print the docstring for an object.
 
         The debugger interface to %pdoc."""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('pdoc')(arg, namespaces=namespaces)
 
     def do_pfile(self, arg):
         """Print (or run through pager) the file where an object is defined.
 
         The debugger interface to %pfile.
         """
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('pfile')(arg, namespaces=namespaces)
 
     def do_pinfo(self, arg):
         """Provide detailed information about an object.
 
         The debugger interface to %pinfo, i.e., obj?."""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('pinfo')(arg, namespaces=namespaces)
 
     def do_pinfo2(self, arg):
         """Provide extra detailed information about an object.
 
         The debugger interface to %pinfo2, i.e., obj??."""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('pinfo2')(arg, namespaces=namespaces)
 
     def do_psource(self, arg):
         """Print (or run through pager) the source code for an object."""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         self.shell.find_line_magic('psource')(arg, namespaces=namespaces)
 
     def checkline(self, filename, lineno):
         """Check whether specified line seems to be executable.
 
         Return `lineno` if it is, 0 if not (e.g. a docstring, comment, blank
         line or EOF). Warning: testing is not comprehensive.
         """
         #######################################################################
         # XXX Hack!  Use python-2.5 compatible code for this call, because with
         # all of our changes, we've drifted from the pdb api in 2.6.  For now,
         # changing:
         #
         #line = linecache.getline(filename, lineno, self.curframe.f_globals)
         # to:
         #
         line = linecache.getline(filename, lineno)
         #
         # does the trick.  But in reality, we need to fix this by reconciling
         # our updates with the new Pdb APIs in Python 2.6.
         #
         # End hack.  The rest of this method is copied verbatim from 2.6 pdb.py
         #######################################################################
 
         if not line:
             print('End of file', file=self.stdout)
             return 0
         line = line.strip()
         # Don't allow setting breakpoint at a blank line
         if (not line or (line[0] == '#') or
              (line[:3] == '"""') or line[:3] == "'''"):
             print('*** Blank or comment', file=self.stdout)
             return 0
         return lineno

IPython/core/hooks.py

@@ -1,230 +1,224 b''
-"""hooks for IPython.
+"""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
+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
+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
+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 profile's ipython_config.py configuration.
+If you wish to define a new hook and activate it, you can make an :doc:`extension
+</config/extensions/index>` or a :ref:`startup script <startup_files>`. For
+example, you could use a startup file like this::
 
-For example, suppose that you have a module called 'myiphooks' in your
-PYTHONPATH, which contains the following definition:
+    import os
 
-import os
-from IPython.core import ipapi
-ip = ipapi.get()
-
-def calljed(self,filename, linenum):
-    "My editor hook calls the jed editor directly."
-    print "Calling my own editor, jed ..."
-    if os.system('jed +%d %s' % (linenum,filename)) != 0:
-        raise TryNext()
+    def calljed(self,filename, linenum):
+        "My editor hook calls the jed editor directly."
+        print "Calling my own editor, jed ..."
+        if os.system('jed +%d %s' % (linenum,filename)) != 0:
+            raise TryNext()
 
-ip.set_hook('editor', calljed)
+    def load_ipython_extension(ip):
+        ip.set_hook('editor', calljed)
 
-You can then enable the functionality by doing 'import myiphooks'
-somewhere in your configuration files or ipython command line.
 """
 
 #*****************************************************************************
 #       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.
 #*****************************************************************************
 
 import os
 import subprocess
 import sys
 
 from IPython.core.error import TryNext
 
 # 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.
 
 __all__ = ['editor', 'fix_error_editor', 'synchronize_with_editor',
            'input_prefilter', 'shutdown_hook', 'late_startup_hook',
            'show_in_pager','pre_prompt_hook',
            'pre_run_code_hook', 'clipboard_get']
 
 def editor(self, filename, linenum=None, wait=True):
     """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.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
     proc = subprocess.Popen('%s %s %s' % (editor, linemark, filename),
                             shell=True)
     if wait and proc.wait() != 0:
         raise 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.editor) != 'vim':
         self.hooks.editor(filename,linenum)
         return
     t = vim_quickfix_file()
     try:
         if os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name):
             raise TryNext()
     finally:
         t.close()
 
 
 def synchronize_with_editor(self, filename, linenum, column):
         pass
 
 
 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"""
         last_exc = TryNext()
         for prio,cmd in self.chain:
             #print "prio",prio,"cmd",cmd #dbg
             try:
                 return cmd(*args, **kw)
             except TryNext as exc:
                 last_exc = exc
         # if no function will accept it, raise TryNext up to the caller
         raise last_exc
 
     def __str__(self):
         return str(self.chain)
 
     def add(self, func, priority=0):
         """ Add a func to the cmd chain with given priority """
         self.chain.append((priority, func))
         self.chain.sort(key=lambda x: x[0])
 
     def __iter__(self):
         """ Return all objects in chain.
 
         Handy if the objects are not callable.
         """
         return iter(self.chain)
 
 
 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 show_in_pager(self,s):
     """ Run a string through pager """
     # raising TryNext here will use the default paging functionality
     raise 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_run_code_hook(self):
     """ Executed before running the (prefiltered) code in IPython """
     return None
 
 
 def clipboard_get(self):
     """ Get text from the clipboard.
     """
     from IPython.lib.clipboard import (
         osx_clipboard_get, tkinter_clipboard_get,
         win32_clipboard_get
     )
     if sys.platform == 'win32':
         chain = [win32_clipboard_get, tkinter_clipboard_get]
     elif sys.platform == 'darwin':
         chain = [osx_clipboard_get, tkinter_clipboard_get]
     else:
         chain = [tkinter_clipboard_get]
     dispatcher = CommandChainDispatcher()
     for func in chain:
         dispatcher.add(func)
     text = dispatcher()
     return text

IPython/core/magics/history.py

@@ -1,312 +1,319 b''
 """Implementation of magic functions related to History.
 """
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2012, IPython Development Team.
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Stdlib
 import os
 from io import open as io_open
 from IPython.external.argparse import Action
 
 # Our own packages
 from IPython.core.error import StdinNotImplementedError
 from IPython.core.magic import Magics, magics_class, line_magic
 from IPython.core.magic_arguments import (argument, magic_arguments,
                                           parse_argstring)
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils import io
 
 #-----------------------------------------------------------------------------
 # Magics class implementation
 #-----------------------------------------------------------------------------
 
 
 _unspecified = object()
 
 
 @magics_class
 class HistoryMagics(Magics):
 
     @magic_arguments()
     @argument(
         '-n', dest='print_nums', action='store_true', default=False,
         help="""
         print line numbers for each input.
         This feature is only available if numbered prompts are in use.
         """)
     @argument(
         '-o', dest='get_output', action='store_true', default=False,
         help="also print outputs for each input.")
     @argument(
         '-p', dest='pyprompts', action='store_true', default=False,
         help="""
         print classic '>>>' python prompts before each input.
         This is useful for making documentation, and in conjunction
         with -o, for producing doctest-ready output.
         """)
     @argument(
         '-t', dest='raw', action='store_false', default=True,
         help="""
         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 'get_ipython().magic("%%cd /")' instead of '%%cd /'.
         """)
     @argument(
         '-f', dest='filename',
         help="""
         FILENAME: instead of printing the output to the screen, redirect
         it to the given file.  The file is always overwritten, though *when
         it can*, IPython asks for confirmation first. In particular, running
         the command 'history -f FILENAME' from the IPython Notebook
         interface will replace FILENAME even if it already exists *without*
         confirmation.
         """)
     @argument(
         '-g', dest='pattern', nargs='*', default=None,
         help="""
         treat the arg as a glob pattern to search for in (full) history.
         This includes the saved history (almost all commands ever written).
         The pattern may contain '?' to match one unknown character and '*'
         to match any number of unknown characters. Use '%%hist -g' to show
         full saved history (may be very long).
         """)
     @argument(
         '-l', dest='limit', type=int, nargs='?', default=_unspecified,
         help="""
         get the last n lines from all sessions. Specify n as a single
         arg, or the default is the last 10 lines.
         """)
     @argument(
         '-u', dest='unique', action='store_true',
         help="""
         when searching history using `-g`, show only unique history.
         """)
     @argument('range', nargs='*')
     @skip_doctest
     @line_magic
     def history(self, parameter_s = ''):
         """Print input history (_i<n> variables), with most recent last.
 
         By default, input history is printed without line numbers so it can be
         directly pasted into an editor. Use -n to show them.
 
         By default, all input history from the current session is displayed.
         Ranges of history can be indicated using the syntax:
-        4      : Line 4, current session
-        4-6    : Lines 4-6, current session
-        243/1-5: Lines 1-5, session 243
-        ~2/7   : Line 7, session 2 before current
-        ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
-                    of 6 sessions ago.
+        
+        ``4``
+            Line 4, current session
+        ``4-6``
+            Lines 4-6, current session
+        ``243/1-5``
+            Lines 1-5, session 243
+        ``~2/7``
+            Line 7, session 2 before current
+        ``~8/1-~6/5``
+            From the first line of 8 sessions ago, to the fifth line of 6
+            sessions ago.
+        
         Multiple ranges can be entered, separated by spaces
 
         The same syntax is used by %macro, %save, %edit, %rerun
 
         Examples
         --------
         ::
 
           In [6]: %history -n 4-6
           4:a = 12
           5:print a**2
           6:%history -n 4-6
 
         """
 
         args = parse_argstring(self.history, parameter_s)
 
         # For brevity
         history_manager = self.shell.history_manager
 
         def _format_lineno(session, line):
             """Helper function to format line numbers properly."""
             if session in (0, history_manager.session_number):
                 return str(line)
             return "%s/%s" % (session, line)
 
         # Check if output to specific file was requested.
         outfname = args.filename
         if not outfname:
             outfile = io.stdout  # default
             # We don't want to close stdout at the end!
             close_at_end = False
         else:
             if os.path.exists(outfname):
                 try:
                     ans = io.ask_yes_no("File %r exists. Overwrite?" % outfname)
                 except StdinNotImplementedError:
                     ans = True
                 if not ans:
                     print('Aborting.')
                     return
                 print("Overwriting file.")
             outfile = io_open(outfname, 'w', encoding='utf-8')
             close_at_end = True
 
         print_nums = args.print_nums
         get_output = args.get_output
         pyprompts = args.pyprompts
         raw = args.raw
 
         pattern = None
         limit = None if args.limit is _unspecified else args.limit
 
         if args.pattern is not None:
             if args.pattern:
                 pattern = "*" + " ".join(args.pattern) + "*"
             else:
                 pattern = "*"
             hist = history_manager.search(pattern, raw=raw, output=get_output,
                                           n=limit, unique=args.unique)
             print_nums = True
         elif args.limit is not _unspecified:
             n = 10 if limit is None else limit
             hist = history_manager.get_tail(n, raw=raw, output=get_output)
         else:
             if args.range:      # Get history by ranges
                 hist = history_manager.get_range_by_str(" ".join(args.range),
                                                         raw, get_output)
             else:               # Just get history for the current session
                 hist = history_manager.get_range(raw=raw, output=get_output)
 
         # We could be displaying the entire history, so let's not try to pull
         # it into a list in memory. Anything that needs more space will just
         # misalign.
         width = 4
 
         for session, lineno, inline in hist:
             # Print user history with tabs expanded to 4 spaces.  The GUI
             # clients use hard tabs for easier usability in auto-indented code,
             # but we want to produce PEP-8 compliant history for safe pasting
             # into an editor.
             if get_output:
                 inline, output = inline
             inline = inline.expandtabs(4).rstrip()
 
             multiline = "\n" in inline
             line_sep = '\n' if multiline else ' '
             if print_nums:
                 print(u'%s:%s' % (_format_lineno(session, lineno).rjust(width),
                         line_sep),  file=outfile, end=u'')
             if pyprompts:
                 print(u">>> ", end=u"", file=outfile)
                 if multiline:
                     inline = "\n... ".join(inline.splitlines()) + "\n..."
             print(inline, file=outfile)
             if get_output and output:
                 print(output, file=outfile)
 
         if close_at_end:
             outfile.close()
 
     @line_magic
     def recall(self, arg):
         r"""Repeat a command, or get command to input line for editing.
 
         %recall and %rep are equivalent.
 
         - %recall (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::
 
              In[1]: l = ["hei", "vaan"]
              In[2]: "".join(l)
             Out[2]: heivaan
              In[3]: %recall
              In[4]: heivaan_ <== cursor blinking
 
         %recall 45
 
         Place history line 45 on the next input prompt. Use %hist to find
         out the number.
 
         %recall 1-4
 
         Combine the specified lines into one cell, and place it on the next
         input prompt. See %history for the slice syntax.
 
         %recall foo+bar
 
         If foo+bar can be evaluated in the user namespace, the result is
         placed at the next input prompt. Otherwise, the history is searched
         for lines which contain that substring, and the most recent one is
         placed at the next input prompt.
         """
         if not arg:                 # Last output
             self.shell.set_next_input(str(self.shell.user_ns["_"]))
             return
                                     # Get history range
         histlines = self.shell.history_manager.get_range_by_str(arg)
         cmd = "\n".join(x[2] for x in histlines)
         if cmd:
             self.shell.set_next_input(cmd.rstrip())
             return
 
         try:                        # Variable in user namespace
             cmd = str(eval(arg, self.shell.user_ns))
         except Exception:           # Search for term in history
             histlines = self.shell.history_manager.search("*"+arg+"*")
             for h in reversed([x[2] for x in histlines]):
                 if 'recall' in h or 'rep' in h:
                     continue
                 self.shell.set_next_input(h.rstrip())
                 return
         else:
             self.shell.set_next_input(cmd.rstrip())
         print("Couldn't evaluate or find in history:", arg)
 
     @line_magic
     def rerun(self, parameter_s=''):
         """Re-run previous input
 
         By default, you can specify ranges of input history to be repeated
         (as with %history). With no arguments, it will repeat the last line.
 
         Options:
 
           -l <n> : Repeat the last n lines of input, not including the
           current command.
 
           -g foo : Repeat the most recent line which contains foo
         """
         opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
         if "l" in opts:         # Last n lines
             n = int(opts['l'])
             hist = self.shell.history_manager.get_tail(n)
         elif "g" in opts:       # Search
             p = "*"+opts['g']+"*"
             hist = list(self.shell.history_manager.search(p))
             for l in reversed(hist):
                 if "rerun" not in l[2]:
                     hist = [l]     # The last match which isn't a %rerun
                     break
             else:
                 hist = []          # No matches except %rerun
         elif args:              # Specify history ranges
             hist = self.shell.history_manager.get_range_by_str(args)
         else:                   # Last line
             hist = self.shell.history_manager.get_tail(1)
         hist = [x[2] for x in hist]
         if not hist:
             print("No lines in history match specification")
             return
         histlines = "\n".join(hist)
         print("=== Executing: ===")
         print(histlines)
         print("=== Output: ===")
         self.shell.run_cell("\n".join(hist), store_history=False)

IPython/core/payloadpage.py

@@ -1,96 +1,96 b''
 # encoding: utf-8
 """
 A payload based version of page.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Third-party
 try:
     from docutils.core import publish_string
 except ImportError:
     # html paging won't be available, but we don't raise any errors.  It's a
     # purely optional feature.
     pass
 
 # Our own
 from IPython.core.interactiveshell import InteractiveShell
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 def page(strng, start=0, screen_lines=0, pager_cmd=None,
          html=None, auto_html=False):
     """Print a string, piping through a pager.
 
     This version ignores the screen_lines and pager_cmd arguments and uses
     IPython's payload system instead.
 
     Parameters
     ----------
     strng : str
       Text to page.
 
     start : int
       Starting line at which to place the display.
     
     html : str, optional
       If given, an html string to send as well.
 
     auto_html : bool, optional
       If true, the input string is assumed to be valid reStructuredText and is
       converted to HTML with docutils.  Note that if docutils is not found,
       this option is silently ignored.
 
-    Note
-    ----
+    Notes
+    -----
 
     Only one of the ``html`` and ``auto_html`` options can be given, not
     both.
     """
 
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0, start)
     shell = InteractiveShell.instance()
 
     if auto_html:
         try:
             # These defaults ensure user configuration variables for docutils
             # are not loaded, only our config is used here.
             defaults = {'file_insertion_enabled': 0,
                         'raw_enabled': 0,
                         '_disable_config': 1}
             html = publish_string(strng, writer_name='html',
                                   settings_overrides=defaults)
         except:
             pass
         
     payload = dict(
         source='IPython.zmq.page.page',
         text=strng,
         html=html,
         start_line_number=start
         )
     shell.payload_manager.write_payload(payload)
 
 
 def install_payload_page():
     """Install this version of page as IPython.core.page.page."""
     from IPython.core import page as corepage
     corepage.page = page

IPython/core/ultratb.py

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

IPython/lib/display.py

@@ -1,287 +1,291 b''
 """Various display related classes.
 
 Authors : MinRK, gregcaporaso, dannystaple
 """
 import urllib
 
 from os.path import exists, isfile, splitext, abspath, join, isdir
 from os import walk
 
 
 class YouTubeVideo(object):
     """Class for embedding a YouTube Video in an IPython session, based on its video id.
 
     e.g. to embed the video on this page:
 
     http://www.youtube.com/watch?v=foo
 
     you would do:
 
     vid = YouTubeVideo("foo")
     display(vid)
     
     To start from 30 seconds:
     
     vid = YouTubeVideo("abc", start=30)
     display(vid)
     
     To calculate seconds from time as hours, minutes, seconds use:
     start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
 
     Other parameters can be provided as documented at 
     https://developers.google.com/youtube/player_parameters#parameter-subheader
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         self.id = id
         self.width = width
         self.height = height
         self.params = kwargs
 
     def _repr_html_(self):
         """return YouTube embed iframe for this video id"""
         if self.params:
             params = "?" + urllib.urlencode(self.params)
         else:
             params = ""
         return """
             <iframe
                 width="%i"
                 height="%i"
                 src="http://www.youtube.com/embed/%s%s"
                 frameborder="0"
                 allowfullscreen
             ></iframe>
         """ % (self.width, self.height, self.id, params)
 
 class FileLink(object):
     """Class for embedding a local file link in an IPython session, based on path
 
     e.g. to embed a link that was generated in the IPython notebook as my/data.txt
 
-    you would do:
+    you would do::
 
-    local_file = FileLink("my/data.txt")
-    display(local_file)
+        local_file = FileLink("my/data.txt")
+        display(local_file)
     
-    or in the HTML notebook, just
+    or in the HTML notebook, just::
     
-    FileLink("my/data.txt")
+        FileLink("my/data.txt")
     """
     
     html_link_str = "<a href='%s' target='_blank'>%s</a>"
     
     def __init__(self,
                  path,
                  url_prefix='files/',
                  result_html_prefix='',
                  result_html_suffix='<br>'):
         """
-            path : path to the file or directory that should be formatted
-            directory_prefix : prefix to be prepended to all files to form a
-             working link [default: 'files']
-            result_html_prefix : text to append to beginning to link
-             [default: none]
-            result_html_suffix : text to append at the end of link
-             [default: '<br>']
+        Parameters
+        ----------
+        path : str
+            path to the file or directory that should be formatted
+        directory_prefix : str
+            prefix to be prepended to all files to form a working link [default:
+            'files']
+        result_html_prefix : str
+            text to append to beginning to link [default: none]
+        result_html_suffix : str 
+            text to append at the end of link [default: '<br>']
         """
         if isdir(path):
             raise ValueError,\
              ("Cannot display a directory using FileLink. "
               "Use FileLinks to display '%s'." % path)
         self.path = path
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
     
     def _format_path(self):
         fp = ''.join([self.url_prefix,self.path])
         return ''.join([self.result_html_prefix,
                         self.html_link_str % (fp, self.path),
                         self.result_html_suffix])
         
     def _repr_html_(self):
         """return html link to file
         """
         if not exists(self.path):
             return ("Path (<tt>%s</tt>) doesn't exist. " 
                     "It may still be in the process of "
                     "being generated, or you may have the "
                     "incorrect path." % self.path)
         
         return self._format_path()
     
     def __repr__(self):
         """return absolute path to file
         """
         return abspath(self.path)
 
 class FileLinks(FileLink):
     """Class for embedding local file links in an IPython session, based on path
 
     e.g. to embed links to files that were generated in the IPython notebook under my/data
 
     you would do:
 
     local_files = FileLinks("my/data")
     display(local_files)
     
     or in the HTML notebook, just
     
     FileLinks("my/data")
     
     """
     def __init__(self,
                  path,
                  url_prefix='files/',
                  included_suffixes=None,
                  result_html_prefix='',
                  result_html_suffix='<br>',
                  notebook_display_formatter=None,
                  terminal_display_formatter=None):
         """
             included_suffixes : list of filename suffixes to include when
              formatting output [default: include all files]
              
             See the FileLink (baseclass of LocalDirectory) docstring for 
              information on additional parameters.
              
             notebook_display_formatter : func used to format links for display 
              in the notebook. See discussion of formatter function below.
             
             terminal_display_formatter : func used to format links for display 
              in the terminal. See discussion of formatter function below.
              
             
             Passing custom formatter functions
             ----------------------------------
              Formatter functions must be of the form:
               f(dirname, fnames, included_suffixes)
                dirname : the name of a directory (a string), 
                fnames :  a list of the files in that directory 
                included_suffixes : a list of the file suffixes that should be 
                                    included in the output (passing None means 
                                    to include all suffixes in the output in
                                    the built-in formatters)
                
                returns a list of lines that should will be print in the 
                notebook (if passing notebook_display_formatter) or the terminal
                (if passing terminal_display_formatter). This function is iterated 
                over for each directory in self.path. Default formatters are in 
                place, can be passed here to support alternative formatting.
             
         """
         if isfile(path):
             raise ValueError,\
              ("Cannot display a file using FileLinks. "
               "Use FileLink to display '%s'." % path)
         self.included_suffixes = included_suffixes
         # remove trailing slashs for more consistent output formatting
         path = path.rstrip('/')
         
         self.path = path
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
         
         self.notebook_display_formatter = \
              notebook_display_formatter or self._get_notebook_display_formatter()
         self.terminal_display_formatter = \
              terminal_display_formatter or self._get_terminal_display_formatter()
     
     def _get_display_formatter(self,
                                dirname_output_format,
                                fname_output_format,
                                fp_format):
         """ generate built-in formatter function
            
            this is used to define both the notebook and terminal built-in 
             formatters as they only differ by some wrapper text for each entry
         
            dirname_output_format: string to use for formatting directory 
             names, dirname will be substituted for a single "%s" which
             must appear in this string
            fname_output_format: string to use for formatting file names,
             if a single "%s" appears in the string, fname will be substituted
             if two "%s" appear in the string, the path to fname will be 
              substituted for the first and fname will be substituted for the
              second
            fp_format: string to use for formatting filepaths, must contain
             exactly two "%s" and the dirname will be subsituted for the first
             and fname will be substituted for the second
         """
         def f(dirname, fnames, included_suffixes=None):
             result = []
             # begin by figuring out which filenames, if any, 
             # are going to be displayed
             display_fnames = []
             for fname in fnames:
                 if (isfile(join(dirname,fname)) and
                        (included_suffixes == None or
                         splitext(fname)[1] in included_suffixes)):
                       display_fnames.append(fname)
         
             if len(display_fnames) == 0:
                 # if there are no filenames to display, don't print anything
                 # (not even the directory name)
                 pass
             else:
                 # otherwise print the formatted directory name followed by 
                 # the formatted filenames
                 dirname_output_line = dirname_output_format % dirname
                 result.append(dirname_output_line)
                 for fname in display_fnames:
                     fp = fp_format % (dirname,fname)
                     try:
                         # output can include both a filepath and a filename...
                         fname_output_line = fname_output_format % (fp, fname)
                     except TypeError:
                         # ... or just a single filepath
                         fname_output_line = fname_output_format % fname
                     result.append(fname_output_line)
             return result
         return f
 
     def _get_notebook_display_formatter(self,
                                         spacer="&nbsp;&nbsp;"):
         """ generate function to use for notebook formatting
         """
         dirname_output_format = \
          self.result_html_prefix + "%s/" + self.result_html_suffix
         fname_output_format = \
          self.result_html_prefix + spacer + self.html_link_str + self.result_html_suffix
         fp_format = self.url_prefix + '%s/%s'
         
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format)
 
     def _get_terminal_display_formatter(self,
                                         spacer="  "):
         """ generate function to use for terminal formatting
         """
         dirname_output_format = "%s/"
         fname_output_format = spacer + "%s"
         fp_format = '%s/%s'
         
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format)
     
     def _format_path(self):
         result_lines = []
         walked_dir = list(walk(self.path))
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.notebook_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)
     
     def __repr__(self):
         """return newline-separated absolute paths
         """
         result_lines = []
         walked_dir = list(walk(self.path))
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.terminal_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)

IPython/lib/inputhook.py

@@ -1,529 +1,529 b''
 # coding: utf-8
 """
 Inputhook management for GUI event loop integration.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 try:
     import ctypes
 except ImportError:
     ctypes = None
 import os
 import sys
 from distutils.version import LooseVersion as V
 
 from IPython.utils.warn import warn
 
 #-----------------------------------------------------------------------------
 # Constants
 #-----------------------------------------------------------------------------
 
 # Constants for identifying the GUI toolkits.
 GUI_WX = 'wx'
 GUI_QT = 'qt'
 GUI_QT4 = 'qt4'
 GUI_GTK = 'gtk'
 GUI_TK = 'tk'
 GUI_OSX = 'osx'
 GUI_GLUT = 'glut'
 GUI_PYGLET = 'pyglet'
 GUI_GTK3 = 'gtk3'
 GUI_NONE = 'none' # i.e. disable
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 def _stdin_ready_posix():
     """Return True if there's something to read on stdin (posix version)."""
     infds, outfds, erfds = select.select([sys.stdin],[],[],0)
     return bool(infds)
 
 def _stdin_ready_nt():
     """Return True if there's something to read on stdin (nt version)."""
     return msvcrt.kbhit()
 
 def _stdin_ready_other():
     """Return True, assuming there's something to read on stdin."""
     return True #
 
 
 def _ignore_CTRL_C_posix():
     """Ignore CTRL+C (SIGINT)."""
     signal.signal(signal.SIGINT, signal.SIG_IGN)
 
 def _allow_CTRL_C_posix():
     """Take CTRL+C into account (SIGINT)."""
     signal.signal(signal.SIGINT, signal.default_int_handler)
 
 def _ignore_CTRL_C_other():
     """Ignore CTRL+C (not implemented)."""
     pass
 
 def _allow_CTRL_C_other():
     """Take CTRL+C into account (not implemented)."""
     pass
 
 if os.name == 'posix':
     import select
     import signal
     stdin_ready = _stdin_ready_posix
     ignore_CTRL_C = _ignore_CTRL_C_posix
     allow_CTRL_C = _allow_CTRL_C_posix
 elif os.name == 'nt':
     import msvcrt
     stdin_ready = _stdin_ready_nt
     ignore_CTRL_C = _ignore_CTRL_C_other
     allow_CTRL_C = _allow_CTRL_C_other
 else:
     stdin_ready = _stdin_ready_other
     ignore_CTRL_C = _ignore_CTRL_C_other
     allow_CTRL_C = _allow_CTRL_C_other
 
 
 #-----------------------------------------------------------------------------
 # Main InputHookManager class
 #-----------------------------------------------------------------------------
 
 
 class InputHookManager(object):
     """Manage PyOS_InputHook for different GUI toolkits.
 
     This class installs various hooks under ``PyOSInputHook`` to handle
     GUI event loop integration.
     """
     
     def __init__(self):
         if ctypes is None:
             warn("IPython GUI event loop requires ctypes, %gui will not be available")
             return
         self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
         self._apps = {}
         self._reset()
 
     def _reset(self):
         self._callback_pyfunctype = None
         self._callback = None
         self._installed = False
         self._current_gui = None
 
     def get_pyos_inputhook(self):
         """Return the current PyOS_InputHook as a ctypes.c_void_p."""
         return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
 
     def get_pyos_inputhook_as_func(self):
         """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE."""
         return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
 
     def set_inputhook(self, callback):
         """Set PyOS_InputHook to callback and return the previous one."""
         # On platforms with 'readline' support, it's all too likely to
         # have a KeyboardInterrupt signal delivered *even before* an
         # initial ``try:`` clause in the callback can be executed, so
         # we need to disable CTRL+C in this situation.
         ignore_CTRL_C()
         self._callback = callback
         self._callback_pyfunctype = self.PYFUNC(callback)
         pyos_inputhook_ptr = self.get_pyos_inputhook()
         original = self.get_pyos_inputhook_as_func()
         pyos_inputhook_ptr.value = \
             ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
         self._installed = True
         return original
 
     def clear_inputhook(self, app=None):
         """Set PyOS_InputHook to NULL and return the previous one.
 
         Parameters
         ----------
         app : optional, ignored
           This parameter is allowed only so that clear_inputhook() can be
           called with a similar interface as all the ``enable_*`` methods.  But
           the actual value of the parameter is ignored.  This uniform interface
           makes it easier to have user-level entry points in the main IPython
           app like :meth:`enable_gui`."""
         pyos_inputhook_ptr = self.get_pyos_inputhook()
         original = self.get_pyos_inputhook_as_func()
         pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
         allow_CTRL_C()
         self._reset()
         return original
 
     def clear_app_refs(self, gui=None):
         """Clear IPython's internal reference to an application instance.
 
         Whenever we create an app for a user on qt4 or wx, we hold a
         reference to the app.  This is needed because in some cases bad things
         can happen if a user doesn't hold a reference themselves.  This
         method is provided to clear the references we are holding.
 
         Parameters
         ----------
         gui : None or str
             If None, clear all app references.  If ('wx', 'qt4') clear
             the app for that toolkit.  References are not held for gtk or tk
             as those toolkits don't have the notion of an app.
         """
         if gui is None:
             self._apps = {}
         elif gui in self._apps:
             del self._apps[gui]
 
     def enable_wx(self, app=None):
         """Enable event loop integration with wxPython.
 
         Parameters
         ----------
         app : WX Application, optional.
             Running application to use.  If not given, we probe WX for an
             existing application object, and create a new one if none is found.
 
         Notes
         -----
         This methods sets the ``PyOS_InputHook`` for wxPython, which allows
         the wxPython to integrate with terminal based applications like
         IPython.
 
         If ``app`` is not given we probe for an existing one, and return it if
         found.  If no existing app is found, we create an :class:`wx.App` as
         follows::
 
             import wx
             app = wx.App(redirect=False, clearSigInt=False)
         """
         import wx
         
         wx_version = V(wx.__version__).version
         
         if wx_version < [2, 8]:
             raise ValueError("requires wxPython >= 2.8, but you have %s" % wx.__version__)
         
         from IPython.lib.inputhookwx import inputhook_wx
         self.set_inputhook(inputhook_wx)
         self._current_gui = GUI_WX
         import wx
         if app is None:
             app = wx.GetApp()
         if app is None:
             app = wx.App(redirect=False, clearSigInt=False)
         app._in_event_loop = True
         self._apps[GUI_WX] = app
         return app
 
     def disable_wx(self):
         """Disable event loop integration with wxPython.
 
         This merely sets PyOS_InputHook to NULL.
         """
         if GUI_WX in self._apps:
             self._apps[GUI_WX]._in_event_loop = False
         self.clear_inputhook()
 
     def enable_qt4(self, app=None):
         """Enable event loop integration with PyQt4.
         
         Parameters
         ----------
         app : Qt Application, optional.
             Running application to use.  If not given, we probe Qt for an
             existing application object, and create a new one if none is found.
 
         Notes
         -----
         This methods sets the PyOS_InputHook for PyQt4, which allows
         the PyQt4 to integrate with terminal based applications like
         IPython.
 
         If ``app`` is not given we probe for an existing one, and return it if
         found.  If no existing app is found, we create an :class:`QApplication`
         as follows::
 
             from PyQt4 import QtCore
             app = QtGui.QApplication(sys.argv)
         """
         from IPython.lib.inputhookqt4 import create_inputhook_qt4
         app, inputhook_qt4 = create_inputhook_qt4(self, app)
         self.set_inputhook(inputhook_qt4)
 
         self._current_gui = GUI_QT4
         app._in_event_loop = True
         self._apps[GUI_QT4] = app
         return app
 
     def disable_qt4(self):
         """Disable event loop integration with PyQt4.
 
         This merely sets PyOS_InputHook to NULL.
         """
         if GUI_QT4 in self._apps:
             self._apps[GUI_QT4]._in_event_loop = False
         self.clear_inputhook()
 
     def enable_gtk(self, app=None):
         """Enable event loop integration with PyGTK.
 
         Parameters
         ----------
         app : ignored
            Ignored, it's only a placeholder to keep the call signature of all
            gui activation methods consistent, which simplifies the logic of
            supporting magics.
 
         Notes
         -----
         This methods sets the PyOS_InputHook for PyGTK, which allows
         the PyGTK to integrate with terminal based applications like
         IPython.
         """
         import gtk
         try:
             gtk.set_interactive(True)
             self._current_gui = GUI_GTK
         except AttributeError:
             # For older versions of gtk, use our own ctypes version
             from IPython.lib.inputhookgtk import inputhook_gtk
             self.set_inputhook(inputhook_gtk)
             self._current_gui = GUI_GTK
 
     def disable_gtk(self):
         """Disable event loop integration with PyGTK.
         
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
     def enable_tk(self, app=None):
         """Enable event loop integration with Tk.
 
         Parameters
         ----------
         app : toplevel :class:`Tkinter.Tk` widget, optional.
             Running toplevel widget to use.  If not given, we probe Tk for an
             existing one, and create a new one if none is found.
 
         Notes
         -----
         If you have already created a :class:`Tkinter.Tk` object, the only
         thing done by this method is to register with the
         :class:`InputHookManager`, since creating that object automatically
         sets ``PyOS_InputHook``.
         """
         self._current_gui = GUI_TK
         if app is None:
             import Tkinter
             app = Tkinter.Tk()
             app.withdraw()
             self._apps[GUI_TK] = app
             return app
 
     def disable_tk(self):
         """Disable event loop integration with Tkinter.
         
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
 
     def enable_glut(self, app=None):
         """ Enable event loop integration with GLUT.
 
         Parameters
         ----------
 
         app : ignored
             Ignored, it's only a placeholder to keep the call signature of all
             gui activation methods consistent, which simplifies the logic of
             supporting magics.
 
         Notes
         -----
 
         This methods sets the PyOS_InputHook for GLUT, which allows the GLUT to
         integrate with terminal based applications like IPython. Due to GLUT
         limitations, it is currently not possible to start the event loop
         without first creating a window. You should thus not create another
         window but use instead the created one. See 'gui-glut.py' in the
         docs/examples/lib directory.
         
         The default screen mode is set to:
         glut.GLUT_DOUBLE | glut.GLUT_RGBA | glut.GLUT_DEPTH
         """
 
         import OpenGL.GLUT as glut
         from IPython.lib.inputhookglut import glut_display_mode, \
                                               glut_close, glut_display, \
                                               glut_idle, inputhook_glut
 
         if GUI_GLUT not in self._apps:
             glut.glutInit( sys.argv )
             glut.glutInitDisplayMode( glut_display_mode )
             # This is specific to freeglut
             if bool(glut.glutSetOption):
                 glut.glutSetOption( glut.GLUT_ACTION_ON_WINDOW_CLOSE,
                                     glut.GLUT_ACTION_GLUTMAINLOOP_RETURNS )
             glut.glutCreateWindow( sys.argv[0] )
             glut.glutReshapeWindow( 1, 1 )
             glut.glutHideWindow( )
             glut.glutWMCloseFunc( glut_close )
             glut.glutDisplayFunc( glut_display )
             glut.glutIdleFunc( glut_idle )
         else:
             glut.glutWMCloseFunc( glut_close )
             glut.glutDisplayFunc( glut_display )
             glut.glutIdleFunc( glut_idle)
         self.set_inputhook( inputhook_glut )
         self._current_gui = GUI_GLUT
         self._apps[GUI_GLUT] = True
 
 
     def disable_glut(self):
         """Disable event loop integration with glut.
         
         This sets PyOS_InputHook to NULL and set the display function to a
         dummy one and set the timer to a dummy timer that will be triggered
         very far in the future.
         """
         import OpenGL.GLUT as glut
         from glut_support import glutMainLoopEvent
 
         glut.glutHideWindow() # This is an event to be processed below
         glutMainLoopEvent()
         self.clear_inputhook()
 
     def enable_pyglet(self, app=None):
         """Enable event loop integration with pyglet.
 
         Parameters
         ----------
         app : ignored
            Ignored, it's only a placeholder to keep the call signature of all
            gui activation methods consistent, which simplifies the logic of
            supporting magics.
 
         Notes
         -----
         This methods sets the ``PyOS_InputHook`` for pyglet, which allows
         pyglet to integrate with terminal based applications like
         IPython.
 
         """
         import pyglet
         from IPython.lib.inputhookpyglet import inputhook_pyglet
         self.set_inputhook(inputhook_pyglet)
         self._current_gui = GUI_PYGLET
         return app
 
     def disable_pyglet(self):
         """Disable event loop integration with pyglet.
 
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
     def enable_gtk3(self, app=None):
         """Enable event loop integration with Gtk3 (gir bindings).
 
         Parameters
         ----------
         app : ignored
            Ignored, it's only a placeholder to keep the call signature of all
            gui activation methods consistent, which simplifies the logic of
            supporting magics.
 
         Notes
         -----
         This methods sets the PyOS_InputHook for Gtk3, which allows
         the Gtk3 to integrate with terminal based applications like
         IPython.
         """
         from IPython.lib.inputhookgtk3 import inputhook_gtk3
         self.set_inputhook(inputhook_gtk3)
         self._current_gui = GUI_GTK
 
     def disable_gtk3(self):
         """Disable event loop integration with PyGTK.
 
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
     def current_gui(self):
         """Return a string indicating the currently active GUI or None."""
         return self._current_gui
 
 inputhook_manager = InputHookManager()
 
 enable_wx = inputhook_manager.enable_wx
 disable_wx = inputhook_manager.disable_wx
 enable_qt4 = inputhook_manager.enable_qt4
 disable_qt4 = inputhook_manager.disable_qt4
 enable_gtk = inputhook_manager.enable_gtk
 disable_gtk = inputhook_manager.disable_gtk
 enable_tk = inputhook_manager.enable_tk
 disable_tk = inputhook_manager.disable_tk
 enable_glut = inputhook_manager.enable_glut
 disable_glut = inputhook_manager.disable_glut
 enable_pyglet = inputhook_manager.enable_pyglet
 disable_pyglet = inputhook_manager.disable_pyglet
 enable_gtk3 = inputhook_manager.enable_gtk3
 disable_gtk3 = inputhook_manager.disable_gtk3
 clear_inputhook = inputhook_manager.clear_inputhook
 set_inputhook = inputhook_manager.set_inputhook
 current_gui = inputhook_manager.current_gui
 clear_app_refs = inputhook_manager.clear_app_refs
 
 
 # Convenience function to switch amongst them
 def enable_gui(gui=None, app=None):
     """Switch amongst GUI input hooks by name.
 
     This is just a utility wrapper around the methods of the InputHookManager
     object.
 
     Parameters
     ----------
     gui : optional, string or None
       If None (or 'none'), clears input hook, otherwise it must be one
       of the recognized GUI names (see ``GUI_*`` constants in module).
 
     app : optional, existing application object.
       For toolkits that have the concept of a global app, you can supply an
       existing one.  If not given, the toolkit will be probed for one, and if
       none is found, a new one will be created.  Note that GTK does not have
-      this concept, and passing an app if `gui`=="GTK" will raise an error.
+      this concept, and passing an app if ``gui=="GTK"`` will raise an error.
 
     Returns
     -------
     The output of the underlying gui switch routine, typically the actual
     PyOS_InputHook wrapper object or the GUI toolkit app created, if there was
     one.
     """
     guis = {None: clear_inputhook,
             GUI_NONE: clear_inputhook,
             GUI_OSX: lambda app=False: None,
             GUI_TK: enable_tk,
             GUI_GTK: enable_gtk,
             GUI_WX: enable_wx,
             GUI_QT: enable_qt4, # qt3 not supported
             GUI_QT4: enable_qt4,
             GUI_GLUT: enable_glut,
             GUI_PYGLET: enable_pyglet,
             GUI_GTK3: enable_gtk3,
             }
     try:
         gui_hook = guis[gui]
     except KeyError:
         e = "Invalid GUI request %r, valid ones are:%s" % (gui, guis.keys())
         raise ValueError(e)
     return gui_hook(app)
 

IPython/testing/decorators.py

@@ -1,358 +1,358 b''
 # -*- coding: utf-8 -*-
 """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.
 
 Included decorators:
 
 
 Lightweight testing that remains unittest-compatible.
 
 - @parametric, for parametric test support that is vastly easier to use than
   nose's for debugging. With ours, if a test fails, the stack under inspection
   is that of the test and not that of the test framework.
 
 - An @as_unittest decorator can be used to tag any normal parameter-less
   function as a unittest TestCase.  Then, both nose and normal unittest will
   recognize it as such.  This will make it easier to migrate away from Nose if
   we ever need/want to while maintaining very lightweight tests.
 
 NOTE: This file contains IPython-specific decorators. Using the machinery in
 IPython.external.decorators, we import either numpy.testing.decorators if numpy is
 available, OR use equivalent code in IPython.external._decorators, which
 we've copied verbatim from numpy.
 
 Authors
 -------
 
 - Fernando Perez <[e-mail]>
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2009-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Stdlib imports
 import inspect
 import sys
 import tempfile
 import unittest
 
 # Third-party imports
 
 # This is Michele Simionato's decorator module, kept verbatim.
 from IPython.external.decorator import decorator
 
 # We already have python3-compliant code for parametric tests
 if sys.version[0]=='2':
     from _paramtestpy2 import parametric, ParametricTestCase
 else:
     from _paramtestpy3 import parametric, ParametricTestCase
 
 # Expose the unittest-driven decorators
 from ipunittest import ipdoctest, ipdocstring
 
 # Grab the numpy-specific decorators which we keep in a file that we
 # occasionally update from upstream: decorators.py is a copy of
 # numpy.testing.decorators, we expose all of it here.
 from IPython.external.decorators import *
 
 # For onlyif_cmd_exists decorator
 from IPython.utils.process import is_cmd_found
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 # Simple example of the basic idea
 def as_unittest(func):
     """Decorator to make a simple function into a normal test via unittest."""
     class Tester(unittest.TestCase):
         def test(self):
             func()
 
     Tester.__name__ = func.__name__
 
     return Tester
 
 # 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.
 
       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
 
 
 # Inspired by numpy's skipif, but uses the full apply_wrapper utility to
 # preserve function metadata better and allows the skip condition to be a
 # callable.
 def skipif(skip_condition, msg=None):
     ''' Make function raise SkipTest exception if skip_condition is true
 
     Parameters
     ----------
     skip_condition : bool or callable.
-    Flag to determine whether to skip test.  If the condition is a
-    callable, it is used at runtime to dynamically make the decision.  This
-    is useful for tests that may require costly imports, to delay the cost
-    until the test suite is actually executed.
+        Flag to determine whether to skip test.  If the condition is a
+        callable, it is used at runtime to dynamically make the decision.  This
+        is useful for tests that may require costly imports, to delay the cost
+        until the test suite is actually executed.
     msg : string
         Message to give on raising a SkipTest exception
 
    Returns
    -------
    decorator : function
        Decorator, which, when applied to a function, causes SkipTest
        to be raised when the skip_condition was True, and the function
        to be called normally otherwise.
 
     Notes
     -----
     You will see from the code that we had to further decorate the
     decorator with the nose.tools.make_decorator function in order to
     transmit function name, and various other metadata.
     '''
 
     def skip_decorator(f):
         # Local import to avoid a hard nose dependency and only incur the
         # import time overhead at actual test-time.
         import nose
 
         # Allow for both boolean or callable skip conditions.
         if callable(skip_condition):
             skip_val = skip_condition
         else:
             skip_val = lambda : skip_condition
 
         def get_msg(func,msg=None):
             """Skip message with information about function being skipped."""
             if msg is None: out = 'Test skipped due to test condition.'
             else: out = msg
             return "Skipping test: %s. %s" % (func.__name__,out)
 
         # We need to define *two* skippers because Python doesn't allow both
         # return with value and yield inside the same function.
         def skipper_func(*args, **kwargs):
             """Skipper for normal test functions."""
             if skip_val():
                 raise nose.SkipTest(get_msg(f,msg))
             else:
                 return f(*args, **kwargs)
 
         def skipper_gen(*args, **kwargs):
             """Skipper for test generators."""
             if skip_val():
                 raise nose.SkipTest(get_msg(f,msg))
             else:
                 for x in f(*args, **kwargs):
                     yield x
 
         # Choose the right skipper to use when building the actual generator.
         if nose.util.isgenerator(f):
             skipper = skipper_gen
         else:
             skipper = skipper_func
 
         return nose.tools.make_decorator(f)(skipper)
 
     return skip_decorator
 
 # A version with the condition set to true, common case just to attach a message
 # to a skip decorator
 def skip(msg=None):
     """Decorator factory - mark a test function for skipping from test suite.
 
     Parameters
     ----------
       msg : string
         Optional message to be added.
 
     Returns
     -------
        decorator : function
          Decorator, which, when applied to a function, causes SkipTest
          to be raised, with the optional message added.
       """
 
     return skipif(True,msg)
 
 
 def onlyif(condition, msg):
     """The reverse from skipif, see skipif for details."""
 
     if callable(condition):
         skip_condition = lambda : not condition()
     else:
         skip_condition = lambda : not condition
 
     return skipif(skip_condition, msg)
 
 #-----------------------------------------------------------------------------
 # Utility functions for decorators
 def module_not_available(module):
     """Can module be imported?  Returns true if module does NOT import.
 
     This is used to make a decorator to skip tests that require module to be
     available, but delay the 'import numpy' to test execution time.
     """
     try:
         mod = __import__(module)
         mod_not_avail = False
     except ImportError:
         mod_not_avail = True
 
     return mod_not_avail
 
 #-----------------------------------------------------------------------------
 # Decorators for public use
 
 # 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.startswith('linux'),
                     "This test does not run under Linux")
 skip_osx = skipif(sys.platform == 'darwin',"This test does not run under OS X")
 
 
 # Decorators to skip tests if not on specific platforms.
 skip_if_not_win32 = skipif(sys.platform != 'win32',
                            "This test only runs under Windows")
 skip_if_not_linux = skipif(not sys.platform.startswith('linux'),
                            "This test only runs under Linux")
 skip_if_not_osx = skipif(sys.platform != 'darwin',
                          "This test only runs under OSX")
 
 # Other skip decorators
 
 # generic skip without module
 skip_without = lambda mod: skipif(module_not_available(mod), "This test requires %s" % mod)
 
 skipif_not_numpy = skip_without('numpy')
 
 skipif_not_matplotlib = skip_without('matplotlib')
 
 skipif_not_sympy = skip_without('sympy')
 
 skip_known_failure = knownfailureif(True,'This test is known to fail')
 
 known_failure_py3 = knownfailureif(sys.version_info[0] >= 3, 
                                     'This test is known to fail on Python 3.')
 
 # A null 'decorator', useful to make more readable code that needs to pick
 # between different decorators based on OS or other conditions
 null_deco = lambda f: f
 
 # Some tests only run where we can use unicode paths. Note that we can't just
 # check os.path.supports_unicode_filenames, which is always False on Linux.
 try:
     f = tempfile.NamedTemporaryFile(prefix=u"tmp€")
 except UnicodeEncodeError:
     unicode_paths = False
 else:
     unicode_paths = True
     f.close()
 
 onlyif_unicode_paths = onlyif(unicode_paths, ("This test is only applicable "
                                     "where we can use unicode in filenames."))
 
 
 def onlyif_cmds_exist(*commands):
     """
     Decorator to skip test when at least one of `commands` is not found.
     """
     for cmd in commands:
         if not is_cmd_found(cmd):
             return skip("This test runs only if command '{0}' "
                         "is installed".format(cmd))
     return null_deco

IPython/testing/tools.py

@@ -1,391 +1,392 b''
 """Generic testing tools.
 
 Authors
 -------
 - Fernando Perez <[e-mail]>
 """
 
 from __future__ import absolute_import
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2009-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import re
 import sys
 import tempfile
 
 from contextlib import contextmanager
 from io import StringIO
 
 try:
     # These tools are used by parts of the runtime, so we make the nose
     # dependency optional at this point.  Nose is a hard dependency to run the
     # test suite, but NOT to use ipython itself.
     import nose.tools as nt
     has_nose = True
 except ImportError:
     has_nose = False
 
 from IPython.config.loader import Config
 from IPython.utils.process import find_cmd, getoutputerror
 from IPython.utils.text import list_strings
 from IPython.utils.io import temp_pyfile, Tee
 from IPython.utils import py3compat
 from IPython.utils.encoding import DEFAULT_ENCODING
 
 from . import decorators as dec
 from . import skipdoctest
 
 #-----------------------------------------------------------------------------
 # Functions and classes
 #-----------------------------------------------------------------------------
 
 # The docstring for full_path doctests differently on win32 (different path
 # separator) so just skip the doctest there.  The example remains informative.
 doctest_deco = skipdoctest.skip_doctest if sys.platform == 'win32' else dec.null_deco
 
 @doctest_deco
 def full_path(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
     --------
 
     >>> full_path('/foo/bar.py',['a.txt','b.txt'])
     ['/foo/a.txt', '/foo/b.txt']
 
     >>> full_path('/foo',['a.txt','b.txt'])
     ['/a.txt', '/b.txt']
 
     If a single file is given, the output is still a list:
     >>> full_path('/foo','a.txt')
     ['/a.txt']
     """
 
     files = list_strings(files)
     base = os.path.split(startPath)[0]
     return [ os.path.join(base,f) for f in files ]
 
 
 def parse_test_output(txt):
     """Parse the output of a test run and return errors, failures.
 
     Parameters
     ----------
     txt : str
       Text output of a test run, assumed to contain a line of one of the
       following forms::
+      
         'FAILED (errors=1)'
         'FAILED (failures=1)'
         'FAILED (errors=1, failures=1)'
 
     Returns
     -------
     nerr, nfail: number of errors and failures.
     """
 
     err_m = re.search(r'^FAILED \(errors=(\d+)\)', txt, re.MULTILINE)
     if err_m:
         nerr = int(err_m.group(1))
         nfail = 0
         return  nerr, nfail
 
     fail_m = re.search(r'^FAILED \(failures=(\d+)\)', txt, re.MULTILINE)
     if fail_m:
         nerr = 0
         nfail = int(fail_m.group(1))
         return  nerr, nfail
 
     both_m = re.search(r'^FAILED \(errors=(\d+), failures=(\d+)\)', txt,
                        re.MULTILINE)
     if both_m:
         nerr = int(both_m.group(1))
         nfail = int(both_m.group(2))
         return  nerr, nfail
 
     # If the input didn't match any of these forms, assume no error/failures
     return 0, 0
 
 
 # So nose doesn't think this is a test
 parse_test_output.__test__ = False
 
 
 def default_argv():
     """Return a valid default argv for creating testing instances of ipython"""
 
     return ['--quick', # so no config file is loaded
             # Other defaults to minimize side effects on stdout
             '--colors=NoColor', '--no-term-title','--no-banner',
             '--autocall=0']
 
 
 def default_config():
     """Return a config object with good defaults for testing."""
     config = Config()
     config.TerminalInteractiveShell.colors = 'NoColor'
     config.TerminalTerminalInteractiveShell.term_title = False,
     config.TerminalInteractiveShell.autocall = 0
     config.HistoryManager.hist_file = tempfile.mktemp(u'test_hist.sqlite')
     config.HistoryManager.db_cache_size = 10000
     return config
 
 
 def ipexec(fname, options=None):
     """Utility to call 'ipython filename'.
 
     Starts IPython witha minimal and safe configuration to make startup as fast
     as possible.
 
     Note that this starts IPython in a subprocess!
 
     Parameters
     ----------
     fname : str
       Name of file to be executed (should have .py or .ipy extension).
 
     options : optional, list
       Extra command-line flags to be passed to IPython.
 
     Returns
     -------
     (stdout, stderr) of ipython subprocess.
     """
     if options is None: options = []
 
     # For these subprocess calls, eliminate all prompt printing so we only see
     # output from script execution
     prompt_opts = [ '--PromptManager.in_template=""',
                     '--PromptManager.in2_template=""',
                     '--PromptManager.out_template=""'
     ]
     cmdargs = ' '.join(default_argv() + prompt_opts + options)
 
     _ip = get_ipython()
     test_dir = os.path.dirname(__file__)
 
     ipython_cmd = find_cmd('ipython3' if py3compat.PY3 else 'ipython')
     # Absolute path for filename
     full_fname = os.path.join(test_dir, fname)
     full_cmd = '%s %s %s' % (ipython_cmd, cmdargs, full_fname)
     #print >> sys.stderr, 'FULL CMD:', full_cmd # dbg
     out, err = getoutputerror(full_cmd)
     # `import readline` causes 'ESC[?1034h' to be output sometimes,
     # so strip that out before doing comparisons
     if out:
         out = re.sub(r'\x1b\[[^h]+h', '', out)
     return out, err
 
 
 def ipexec_validate(fname, expected_out, expected_err='',
                     options=None):
     """Utility to call 'ipython filename' and validate output/error.
 
     This function raises an AssertionError if the validation fails.
 
     Note that this starts IPython in a subprocess!
 
     Parameters
     ----------
     fname : str
       Name of the file to be executed (should have .py or .ipy extension).
 
     expected_out : str
       Expected stdout of the process.
 
     expected_err : optional, str
       Expected stderr of the process.
 
     options : optional, list
       Extra command-line flags to be passed to IPython.
 
     Returns
     -------
     None
     """
 
     import nose.tools as nt
 
     out, err = ipexec(fname, options)
     #print 'OUT', out  # dbg
     #print 'ERR', err  # dbg
     # If there are any errors, we must check those befor stdout, as they may be
     # more informative than simply having an empty stdout.
     if err:
         if expected_err:
             nt.assert_equal("\n".join(err.strip().splitlines()), "\n".join(expected_err.strip().splitlines()))
         else:
             raise ValueError('Running file %r produced error: %r' %
                              (fname, err))
     # If no errors or output on stderr was expected, match stdout
     nt.assert_equal("\n".join(out.strip().splitlines()), "\n".join(expected_out.strip().splitlines()))
 
 
 class TempFileMixin(object):
     """Utility class to create temporary Python/IPython files.
 
     Meant as a mixin class for test cases."""
 
     def mktmp(self, src, ext='.py'):
         """Make a valid python temp file."""
         fname, f = temp_pyfile(src, ext)
         self.tmpfile = f
         self.fname = fname
 
     def tearDown(self):
         if hasattr(self, 'tmpfile'):
             # If the tmpfile wasn't made because of skipped tests, like in
             # win32, there's nothing to cleanup.
             self.tmpfile.close()
             try:
                 os.unlink(self.fname)
             except:
                 # On Windows, even though we close the file, we still can't
                 # delete it.  I have no clue why
                 pass
 
 pair_fail_msg = ("Testing {0}\n\n"
                 "In:\n"
                 "  {1!r}\n"
                 "Expected:\n"
                 "  {2!r}\n"
                 "Got:\n"
                 "  {3!r}\n")
 def check_pairs(func, pairs):
     """Utility function for the common case of checking a function with a
     sequence of input/output pairs.
 
     Parameters
     ----------
     func : callable
       The function to be tested. Should accept a single argument.
     pairs : iterable
       A list of (input, expected_output) tuples.
 
     Returns
     -------
     None. Raises an AssertionError if any output does not match the expected
     value.
     """
     name = getattr(func, "func_name", getattr(func, "__name__", "<unknown>"))
     for inp, expected in pairs:
         out = func(inp)
         assert out == expected, pair_fail_msg.format(name, inp, expected, out)
 
 
 if py3compat.PY3:
     MyStringIO = StringIO
 else:
     # In Python 2, stdout/stderr can have either bytes or unicode written to them,
     # so we need a class that can handle both.
     class MyStringIO(StringIO):
         def write(self, s):
             s = py3compat.cast_unicode(s, encoding=DEFAULT_ENCODING)
             super(MyStringIO, self).write(s)
 
 notprinted_msg = """Did not find {0!r} in printed output (on {1}):
 -------
 {2!s}
 -------
 """
 
 class AssertPrints(object):
     """Context manager for testing that code prints certain text.
     
     Examples
     --------
     >>> with AssertPrints("abc", suppress=False):
     ...     print "abcd"
     ...     print "def"
     ... 
     abcd
     def
     """
     def __init__(self, s, channel='stdout', suppress=True):
         self.s = s
         self.channel = channel
         self.suppress = suppress
     
     def __enter__(self):
         self.orig_stream = getattr(sys, self.channel)
         self.buffer = MyStringIO()
         self.tee = Tee(self.buffer, channel=self.channel)
         setattr(sys, self.channel, self.buffer if self.suppress else self.tee)
     
     def __exit__(self, etype, value, traceback):
         self.tee.flush()
         setattr(sys, self.channel, self.orig_stream)
         printed = self.buffer.getvalue()
         assert self.s in printed, notprinted_msg.format(self.s, self.channel, printed)
         return False
 
 printed_msg = """Found {0!r} in printed output (on {1}):
 -------
 {2!s}
 -------
 """
 
 class AssertNotPrints(AssertPrints):
     """Context manager for checking that certain output *isn't* produced.
     
     Counterpart of AssertPrints"""
     def __exit__(self, etype, value, traceback):
         self.tee.flush()
         setattr(sys, self.channel, self.orig_stream)
         printed = self.buffer.getvalue()
         assert self.s not in printed, printed_msg.format(self.s, self.channel, printed)
         return False
 
 @contextmanager
 def mute_warn():
     from IPython.utils import warn
     save_warn = warn.warn
     warn.warn = lambda *a, **kw: None
     try:
         yield
     finally:
         warn.warn = save_warn
 
 @contextmanager
 def make_tempfile(name):
     """ Create an empty, named, temporary file for the duration of the context.
     """
     f = open(name, 'w')
     f.close()
     try:
         yield
     finally:
         os.unlink(name)
 
 
 @contextmanager
 def monkeypatch(obj, name, attr):
     """
     Context manager to replace attribute named `name` in `obj` with `attr`.
     """
     orig = getattr(obj, name)
     setattr(obj, name, attr)
     yield
     setattr(obj, name, orig)

IPython/utils/encoding.py

@@ -1,56 +1,56 b''
 # coding: utf-8
 """
 Utilities for dealing with text encodings
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2012  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 locale
 
 # to deal with the possibility of sys.std* not being a stream at all
 def get_stream_enc(stream, default=None):
     """Return the given stream's encoding or a default.
 
-    There are cases where sys.std* might not actually be a stream, so
+    There are cases where ``sys.std*`` might not actually be a stream, so
     check for the encoding attribute prior to returning it, and return
-    a default if it doesn't exist or evaluates as False. `default'
+    a default if it doesn't exist or evaluates as False. ``default``
     is None if not provided.
     """
     if not hasattr(stream, 'encoding') or not stream.encoding:
         return default
     else:
         return stream.encoding
 
 # Less conservative replacement for sys.getdefaultencoding, that will try
 # to match the environment.
 # Defined here as central function, so if we find better choices, we
 # won't need to make changes all over IPython.
 def getdefaultencoding():
     """Return IPython's guess for the default encoding for bytes as text.
 
     Asks for stdin.encoding first, to match the calling Terminal, but that
     is often None for subprocesses.  Fall back on locale.getpreferredencoding()
     which should be a sensible platform default (that respects LANG environment),
     and finally to sys.getdefaultencoding() which is the most conservative option,
     and usually ASCII.
     """
     enc = get_stream_enc(sys.stdin)
     if not enc or enc=='ascii':
         try:
             # There are reports of getpreferredencoding raising errors
             # in some cases, which may well be fixed, but let's be conservative here.
             enc = locale.getpreferredencoding()
         except Exception:
             pass
     return enc or sys.getdefaultencoding()
 
 DEFAULT_ENCODING = getdefaultencoding()

IPython/utils/nested_context.py

@@ -1,50 +1,50 b''
 """Backwards compatibility - we use contextlib.nested to support Python 2.6,
 but it's removed in Python 3.2."""
 
 # TODO : Remove this once we drop support for Python 2.6, and use
 # "with a, b:" instead.
 
 import sys
 
 from contextlib import contextmanager
 
 @contextmanager
 def nested(*managers):
     """Combine multiple context managers into a single nested context manager.
 
    This function has been deprecated in favour of the multiple manager form
    of the with statement.
 
    The one advantage of this function over the multiple manager form of the
    with statement is that argument unpacking allows it to be
-   used with a variable number of context managers as follows:
+   used with a variable number of context managers as follows::
 
       with nested(*managers):
           do_something()
 
     """
     exits = []
     vars = []
     exc = (None, None, None)
     try:
         for mgr in managers:
             exit = mgr.__exit__
             enter = mgr.__enter__
             vars.append(enter())
             exits.append(exit)
         yield vars
     except:
         exc = sys.exc_info()
     finally:
         while exits:
             exit = exits.pop()
             try:
                 if exit(*exc):
                     exc = (None, None, None)
             except:
                 exc = sys.exc_info()
         if exc != (None, None, None):
             # Don't rely on sys.exc_info() still containing
             # the right information. Another exception may
             # have been raised and caught by an exit method
             raise exc[0], exc[1], exc[2]

IPython/utils/notification.py

@@ -1,142 +1,142 b''
 # encoding: utf-8
 """
 The IPython Core Notification Center.
 
 See docs/source/development/notification_blueprint.txt for an overview of the
 notification module.
 
 Authors:
 
 * Barry Wark
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 
 class NotificationError(Exception):
     pass
 
 
 class NotificationCenter(object):
     """Synchronous notification center.
 
     Examples
     --------
     Here is a simple example of how to use this::
 
         import IPython.util.notification as notification
         def callback(ntype, theSender, args={}):
             print ntype,theSender,args
 
         notification.sharedCenter.add_observer(callback, 'NOTIFICATION_TYPE', None)
         notification.sharedCenter.post_notification('NOTIFICATION_TYPE', object()) # doctest:+ELLIPSIS
         NOTIFICATION_TYPE ...
     """
     def __init__(self):
         super(NotificationCenter, self).__init__()
         self._init_observers()
 
     def _init_observers(self):
         """Initialize observer storage"""
 
         self.registered_types = set() #set of types that are observed
         self.registered_senders = set() #set of senders that are observed
         self.observers = {} #map (type,sender) => callback (callable)
 
     def post_notification(self, ntype, sender, *args, **kwargs):
         """Post notification to all registered observers.
 
         The registered callback will be called as::
 
             callback(ntype, sender, *args, **kwargs)
 
         Parameters
         ----------
         ntype : hashable
             The notification type.
         sender : hashable
             The object sending the notification.
         *args : tuple
             The positional arguments to be passed to the callback.
         **kwargs : dict
             The keyword argument to be passed to the callback.
 
         Notes
         -----
         * If no registered observers, performance is O(1).
         * Notificaiton order is undefined.
         * Notifications are posted synchronously.
         """
 
         if(ntype==None or sender==None):
             raise NotificationError(
                 "Notification type and sender are required.")
 
         # If there are no registered observers for the type/sender pair
         if((ntype not in self.registered_types and
                 None not in self.registered_types) or
             (sender not in self.registered_senders and
                 None not in self.registered_senders)):
             return
 
         for o in self._observers_for_notification(ntype, sender):
             o(ntype, sender, *args, **kwargs)
 
     def _observers_for_notification(self, ntype, sender):
         """Find all registered observers that should recieve notification"""
 
         keys = (
                    (ntype,sender),
                    (ntype, None),
                    (None, sender),
                    (None,None)
                )
 
         obs = set()
         for k in keys:
             obs.update(self.observers.get(k, set()))
 
         return obs
 
     def add_observer(self, callback, ntype, sender):
         """Add an observer callback to this notification center.
 
         The given callback will be called upon posting of notifications of
         the given type/sender and will receive any additional arguments passed
         to post_notification.
 
         Parameters
         ----------
         callback : callable
             The callable that will be called by :meth:`post_notification`
-            as ``callback(ntype, sender, *args, **kwargs)
+            as ``callback(ntype, sender, *args, **kwargs)``
         ntype : hashable
             The notification type. If None, all notifications from sender
             will be posted.
         sender : hashable
             The notification sender. If None, all notifications of ntype
             will be posted.
         """
         assert(callback != None)
         self.registered_types.add(ntype)
         self.registered_senders.add(sender)
         self.observers.setdefault((ntype,sender), set()).add(callback)
 
     def remove_all_observers(self):
         """Removes all observers from this notification center"""
 
         self._init_observers()
 
 
 
 shared_center = NotificationCenter()

IPython/utils/text.py

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

docs/autogen_api.py

@@ -1,63 +1,65 b''
 #!/usr/bin/env python
 """Script to auto-generate our API docs.
 """
 # stdlib imports
 import os
 import sys
 
 # local imports
 sys.path.append(os.path.abspath('sphinxext'))
 from apigen import ApiDocWriter
 
 #*****************************************************************************
 if __name__ == '__main__':
     pjoin = os.path.join
     package = 'IPython'
     outdir = pjoin('source','api','generated')
     docwriter = ApiDocWriter(package,rst_extension='.txt')
     # You have to escape the . here because . is a special char for regexps.
     # You must do make clean if you change this!
     docwriter.package_skip_patterns += [r'\.fixes$',
                                         r'\.external$',
                                         r'\.extensions',
                                         r'\.kernel\.config',
                                         r'\.attic',
                                         r'\.quarantine',
                                         r'\.deathrow',
                                         r'\.config\.default',
                                         r'\.config\.profile',
                                         r'\.frontend',
                                         r'\.gui',
                                         r'\.kernel',
                                         # For now, the zmq code has
                                         # unconditional top-level code so it's
                                         # not import safe.  This needs fixing
                                         r'\.zmq',
                                         ]
 
     docwriter.module_skip_patterns += [ r'\.core\.fakemodule',
                                         r'\.testing\.iptest',
                                         # Keeping these disabled is OK
                                         r'\.parallel\.controller\.mongodb',
                                         r'\.lib\.inputhookwx',
                                         r'\.lib\.inputhookgtk',
                                         r'\.cocoa',
                                         r'\.ipdoctest',
                                         r'\.Gnuplot',
                                         r'\.frontend\.process\.winprocess',
                                         r'\.Shell',
                                         ]
     
     # If we don't have pexpect, we can't load irunner, so skip any code that
     # depends on it
     try:
         import pexpect
     except ImportError:
         docwriter.module_skip_patterns += [r'\.lib\.irunner',
                                            r'\.testing\.mkdoctests']
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
-    docwriter.write_index(outdir, 'gen',
+    # Write index with .rst extension - we can include it, but Sphinx won't try
+    # to compile it
+    docwriter.write_index(outdir, 'gen.rst',
                           relative_to = pjoin('source','api')
                           )
     print '%d files written' % len(docwriter.written_modules)

docs/source/api/index.txt

@@ -1,12 +1,12 b''
 .. _api-index:
 
 ###################
   The IPython API
 ###################
 
 .. htmlonly::
 
    :Release: |version|
    :Date: |today|
 
-.. include:: generated/gen.txt
+.. include:: generated/gen.rst

docs/source/config/extensions/storemagic.txt

@@ -1,8 +1,8 b''
 .. _extensions_storemagic:
 
 ==========
 storemagic
 ==========
 
 .. automodule:: IPython.extensions.storemagic
-   :members: magic_store
+   :members: store

docs/source/config/overview.txt

@@ -1,552 +1,554 b''
 .. _config_overview:
 
 ============================================
 Overview of the IPython configuration system
 ============================================
 
 This section describes the IPython configuration system. Starting with version
 0.11, IPython has a completely new configuration system that is quite
 different from the older :file:`ipythonrc` or :file:`ipy_user_conf.py`
 approaches. The new configuration system was designed from scratch to address
 the particular configuration needs of IPython. While there are many
 other excellent configuration systems out there, we found that none of them
 met our requirements.
 
 .. warning::
 
     If you are upgrading to version 0.11 of IPython, you will need to migrate
     your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files
     to the new system. You may want to read the section on 
     :ref:`configuring IPython <configuring_ipython>`. There are also some ideas
     `on the IPython wiki <http://wiki.ipython.org/Cookbook/Moving_config_to_IPython_0.11>`_
     about this.
 
 The discussion that follows is focused on teaching users how to configure
 IPython to their liking.  Developers who want to know more about how they
 can enable their objects to take advantage of the configuration system
 should consult our :ref:`developer guide <developer_guide>`
 
 The main concepts
 =================
 
 There are a number of abstractions that the IPython configuration system uses.
 Each of these abstractions is represented by a Python class.
 
 Configuration object: :class:`~IPython.config.loader.Config`
     A configuration object is a simple dictionary-like class that holds
     configuration attributes and sub-configuration objects. These classes
     support dotted attribute style access (``Foo.bar``) in addition to the
     regular dictionary style access (``Foo['bar']``). Configuration objects
     are smart. They know how to merge themselves with other configuration
     objects and they automatically create sub-configuration objects.
 
 Application: :class:`~IPython.config.application.Application`
     An application is a process that does a specific job. The most obvious
     application is the :command:`ipython` command line program. Each
     application reads *one or more* configuration files and a single set of
     command line options
     and then produces a master configuration object for the application. This
     configuration object is then passed to the configurable objects that the
     application creates. These configurable objects implement the actual logic
     of the application and know how to configure themselves given the
     configuration object.
     
     Applications always have a `log` attribute that is a configured Logger.
     This allows centralized logging configuration per-application.
 
 Configurable: :class:`~IPython.config.configurable.Configurable`
     A configurable is a regular Python class that serves as a base class for
     all main classes in an application. The
     :class:`~IPython.config.configurable.Configurable` base class is
     lightweight and only does one things.
 
     This :class:`~IPython.config.configurable.Configurable` is a subclass
     of :class:`~IPython.utils.traitlets.HasTraits` that knows how to configure
     itself. Class level traits with the metadata ``config=True`` become
     values that can be configured from the command line and configuration
     files.
     
     Developers create :class:`~IPython.config.configurable.Configurable`
     subclasses that implement all of the logic in the application. Each of
     these subclasses has its own configuration information that controls how
     instances are created.
 
 Singletons: :class:`~IPython.config.configurable.SingletonConfigurable`
     Any object for which there is a single canonical instance. These are
     just like Configurables, except they have a class method 
     :meth:`~IPython.config.configurable.SingletonConfigurable.instance`,
     that returns the current active instance (or creates one if it
     does not exist).  Examples of singletons include
     :class:`~IPython.config.application.Application`s and
     :class:`~IPython.core.interactiveshell.InteractiveShell`.  This lets
     objects easily connect to the current running Application without passing
     objects around everywhere.  For instance, to get the current running 
     Application instance, simply do: ``app = Application.instance()``.
 
 
 .. note::
 
     Singletons are not strictly enforced - you can have many instances
     of a given singleton class, but the :meth:`instance` method will always
     return the same one.
 
 Having described these main concepts, we can now state the main idea in our
 configuration system: *"configuration" allows the default values of class
 attributes to be controlled on a class by class basis*. Thus all instances of
 a given class are configured in the same way. Furthermore, if two instances
 need to be configured differently, they need to be instances of two different
 classes. While this model may seem a bit restrictive, we have found that it
 expresses most things that need to be configured extremely well. However, it
 is possible to create two instances of the same class that have different
 trait values. This is done by overriding the configuration.
 
 Now, we show what our configuration objects and files look like.
 
 Configuration objects and files
 ===============================
 
 A configuration file is simply a pure Python file that sets the attributes
 of a global, pre-created configuration object.  This configuration object is a 
 :class:`~IPython.config.loader.Config` instance.  While in a configuration
 file, to get a reference to this object, simply call the :func:`get_config`
 function.  We inject this function into the global namespace that the 
 configuration file is executed in.
 
 Here is an example of a super simple configuration file that does nothing::
 
     c = get_config()
 
 Once you get a reference to the configuration object, you simply set
 attributes on it.  All you have to know is:
 
 * The name of each attribute.
 * The type of each attribute.
 
 The answers to these two questions are provided by the various
 :class:`~IPython.config.configurable.Configurable` subclasses that an
 application uses. Let's look at how this would work for a simple configurable
 subclass::
 
     # Sample configurable:
     from IPython.config.configurable import Configurable
     from IPython.utils.traitlets import Int, Float, Unicode, Bool
     
     class MyClass(Configurable):
         name = Unicode(u'defaultname', config=True)
         ranking = Int(0, config=True)
         value = Float(99.0)
         # The rest of the class implementation would go here..
 
 In this example, we see that :class:`MyClass` has three attributes, two
 of whom (``name``, ``ranking``) can be configured.  All of the attributes
 are given types and default values.  If a :class:`MyClass` is instantiated,
 but not configured, these default values will be used.  But let's see how
 to configure this class in a configuration file::
 
     # Sample config file
     c = get_config()
     
     c.MyClass.name = 'coolname'
     c.MyClass.ranking = 10
 
 After this configuration file is loaded, the values set in it will override
 the class defaults anytime a :class:`MyClass` is created.  Furthermore,
 these attributes will be type checked and validated anytime they are set.
 This type checking is handled by the :mod:`IPython.utils.traitlets` module,
 which provides the :class:`Unicode`, :class:`Int` and :class:`Float` types.
 In addition to these traitlets, the :mod:`IPython.utils.traitlets` provides
 traitlets for a number of other types.
 
 .. note::
 
     Underneath the hood, the :class:`Configurable` base class is a subclass of
     :class:`IPython.utils.traitlets.HasTraits`. The
     :mod:`IPython.utils.traitlets` module is a lightweight version of
     :mod:`enthought.traits`. Our implementation is a pure Python subset
     (mostly API compatible) of :mod:`enthought.traits` that does not have any
     of the automatic GUI generation capabilities. Our plan is to achieve 100%
     API compatibility to enable the actual :mod:`enthought.traits` to
     eventually be used instead. Currently, we cannot use
     :mod:`enthought.traits` as we are committed to the core of IPython being
     pure Python.
 
 It should be very clear at this point what the naming convention is for 
 configuration attributes::
 
     c.ClassName.attribute_name = attribute_value
 
 Here, ``ClassName`` is the name of the class whose configuration attribute you
 want to set, ``attribute_name`` is the name of the attribute you want to set
 and ``attribute_value`` the the value you want it to have. The ``ClassName``
 attribute of ``c`` is not the actual class, but instead is another
 :class:`~IPython.config.loader.Config` instance.
 
 .. note::
 
     The careful reader may wonder how the ``ClassName`` (``MyClass`` in
     the above example) attribute of the configuration object ``c`` gets
     created. These attributes are created on the fly by the
     :class:`~IPython.config.loader.Config` instance, using a simple naming
     convention. Any attribute of a :class:`~IPython.config.loader.Config`
     instance whose name begins with an uppercase character is assumed to be a
     sub-configuration and a new empty :class:`~IPython.config.loader.Config`
     instance is dynamically created for that attribute. This allows deeply
     hierarchical information created easily (``c.Foo.Bar.value``) on the fly.
 
 Configuration files inheritance
 ===============================
 
 Let's say you want to have different configuration files for various purposes.
 Our configuration system makes it easy for one configuration file to inherit
 the information in another configuration file. The :func:`load_subconfig`
 command can be used in a configuration file for this purpose. Here is a simple
 example that loads all of the values from the file :file:`base_config.py`::
 
     # base_config.py
     c = get_config()
     c.MyClass.name = 'coolname'
     c.MyClass.ranking = 100
 
 into the configuration file :file:`main_config.py`::
 
     # main_config.py
     c = get_config()
     
     # Load everything from base_config.py
     load_subconfig('base_config.py')
     
     # Now override one of the values
     c.MyClass.name = 'bettername'
 
 In a situation like this the :func:`load_subconfig` makes sure that the
 search path for sub-configuration files is inherited from that of the parent.
 Thus, you can typically put the two in the same directory and everything will
 just work.
 
 You can also load configuration files by profile, for instance:
 
 .. sourcecode:: python
 
     load_subconfig('ipython_config.py', profile='default')
 
 to inherit your default configuration as a starting point.
 
 
 Class based configuration inheritance
 =====================================
 
 There is another aspect of configuration where inheritance comes into play.
 Sometimes, your classes will have an inheritance hierarchy that you want
 to be reflected in the configuration system.  Here is a simple example::
 
     from IPython.config.configurable import Configurable
     from IPython.utils.traitlets import Int, Float, Unicode, Bool
     
     class Foo(Configurable):
         name = Unicode(u'fooname', config=True)
         value = Float(100.0, config=True)
     
     class Bar(Foo):
         name = Unicode(u'barname', config=True)
         othervalue = Int(0, config=True)
 
 Now, we can create a configuration file to configure instances of :class:`Foo`
 and :class:`Bar`::
 
     # config file
     c = get_config()
     
     c.Foo.name = u'bestname'
     c.Bar.othervalue = 10
 
 This class hierarchy and configuration file accomplishes the following:
 
 * The default value for :attr:`Foo.name` and :attr:`Bar.name` will be
   'bestname'.  Because :class:`Bar` is a :class:`Foo` subclass it also
   picks up the configuration information for :class:`Foo`.
 * The default value for :attr:`Foo.value` and :attr:`Bar.value` will be
   ``100.0``, which is the value specified as the class default.
 * The default value for :attr:`Bar.othervalue` will be 10 as set in the
   configuration file.  Because :class:`Foo` is the parent of :class:`Bar`
   it doesn't know anything about the :attr:`othervalue` attribute.
 
 
 .. _ipython_dir:
 
 Configuration file location
 ===========================
 
 So where should you put your configuration files? IPython uses "profiles" for
 configuration, and by default, all profiles will be stored in the so called
 "IPython directory". The location of this directory is determined by the
 following algorithm:
 
 * If the ``ipython-dir`` command line flag is given, its value is used.
 
 * If not, the value returned by :func:`IPython.utils.path.get_ipython_dir`
   is used. This function will first look at the :envvar:`IPYTHONDIR`
   environment variable and then default to a platform-specific default.
   Historical support for the :envvar:`IPYTHON_DIR` environment variable will
   be removed in a future release.
 
 On posix systems (Linux, Unix, etc.), IPython respects the ``$XDG_CONFIG_HOME``
 part of the `XDG Base Directory`_ specification. If ``$XDG_CONFIG_HOME`` is
 defined and exists ( ``XDG_CONFIG_HOME`` has a default interpretation of
 :file:`$HOME/.config`), then IPython's config directory will be located in
 :file:`$XDG_CONFIG_HOME/ipython`.  If users still have an IPython directory
 in :file:`$HOME/.ipython`, then that will be used. in preference to the 
 system default.
 
 For most users, the default value will simply be something like 
 :file:`$HOME/.config/ipython` on Linux, or :file:`$HOME/.ipython`
 elsewhere.
 
 Once the location of the IPython directory has been determined, you need to know
 which profile you are using. For users with a single configuration, this will
 simply be 'default', and will be located in 
 :file:`<IPYTHONDIR>/profile_default`.
 
 The next thing you need to know is what to call your configuration file. The
 basic idea is that each application has its own default configuration filename.
 The default named used by the :command:`ipython` command line program is
 :file:`ipython_config.py`, and *all* IPython applications will use this file.
 Other applications, such as the parallel :command:`ipcluster` scripts or the
 QtConsole will load their own config files *after* :file:`ipython_config.py`. To
 load a particular configuration file instead of the default, the name can be
 overridden by the ``config_file`` command line flag.
 
 To generate the default configuration files, do::
 
     $> ipython profile create
 
 and you will have a default :file:`ipython_config.py` in your IPython directory
 under :file:`profile_default`. If you want the default config files for the
 :mod:`IPython.parallel` applications, add ``--parallel`` to the end of the
 command-line args.
 
 
 Locating these files
 --------------------
 
 From the command-line, you can quickly locate the IPYTHONDIR or a specific
 profile with:
 
 .. sourcecode:: bash
 
     $> ipython locate
     /home/you/.ipython
     
     $> ipython locate profile foo
     /home/you/.ipython/profile_foo
 
 These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`
 and :func:`IPython.utils.path.locate_profile` respectively.
 
 
 .. _Profiles:
 
 Profiles
 ========
 
 A profile is a directory containing configuration and runtime files, such as
 logs, connection info for the parallel apps, and your IPython command history.
 
 The idea is that users often want to maintain a set of configuration files for
 different purposes: one for doing numerical computing with NumPy and SciPy and
 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
 separate configuration files, logs, and histories for each of these purposes.
 
 Let's start by showing how a profile is used:
 
 .. code-block:: bash
 
     $ ipython --profile=sympy
 
 This tells the :command:`ipython` command line program to get its configuration
 from the "sympy" profile. The file names for various profiles do not change. The
 only difference is that profiles are named in a special way. In the case above,
 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`.
 
 The general pattern is this: simply create a new profile with:
 
 .. code-block:: bash
 
     ipython profile create <name>
 
 which adds a directory called ``profile_<name>`` to your IPython directory. Then
 you can load this profile by adding ``--profile=<name>`` to your command line
 options. Profiles are supported by all IPython applications.
 
 IPython ships with some sample profiles in :file:`IPython/config/profile`. If
 you create profiles with the name of one of our shipped profiles, these config
 files will be copied over instead of starting with the automatically generated
 config files.
 
 Security Files
 --------------
 
 If you are using the notebook, qtconsole, or parallel code, IPython stores
 connection information in small JSON files in the active profile's security
 directory. This directory is made private, so only you can see the files inside. If
 you need to move connection files around to other computers, this is where they will
 be. If you want your code to be able to open security files by name, we have a
 convenience function :func:`IPython.utils.path.get_security_file`, which will return
 the absolute path to a security file from its filename and [optionally] profile
 name.
 
+.. _startup_files:
+
 Startup Files
 -------------
 
 If you want some code to be run at the beginning of every IPython session with a
 particular profile, the easiest way is to add Python (.py) or IPython (.ipy) scripts
 to your :file:`<profile>/startup` directory. Files in this directory will always be
 executed as soon as the IPython shell is constructed, and before any other code or
 scripts you have specified. If you have multiple files in the startup directory,
 they will be run in lexicographical order, so you can control the ordering by adding
 a '00-' prefix.
 
 .. note::
 
     Automatic startup files are new in IPython 0.12. Use the
     InteractiveShellApp.exec_files configurable for similar behavior in 0.11.
 
 
 .. _commandline:
 
 Command-line arguments
 ======================
 
 IPython exposes *all* configurable options on the command-line. The command-line
 arguments are generated from the Configurable traits of the classes associated
 with a given Application.  Configuring IPython from the command-line may look
 very similar to an IPython config file
 
 IPython applications use a parser called
 :class:`~IPython.config.loader.KeyValueLoader` to load values into a Config
 object.  Values are assigned in much the same way as in a config file:
 
 .. code-block:: bash
 
     $> ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
 
 Is the same as adding:
 
 .. sourcecode:: python
 
     c.InteractiveShell.use_readline=False
     c.BaseIPythonApplication.profile='myprofile'
 
 to your config file. Key/Value arguments *always* take a value, separated by '='
 and no spaces.
 
 Common Arguments
-****************
+----------------
 
 Since the strictness and verbosity of the KVLoader above are not ideal for everyday
 use, common arguments can be specified as flags_ or aliases_.
 
 Flags and Aliases are handled by :mod:`argparse` instead, allowing for more flexible
 parsing. In general, flags and aliases are prefixed by ``--``, except for those
 that are single characters, in which case they can be specified with a single ``-``, e.g.:
 
 .. code-block:: bash
 
     $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
 
 Aliases
--------
+*******
 
 For convenience, applications have a mapping of commonly used traits, so you don't have
 to specify the whole class name:
 
 .. code-block:: bash
 
     $> ipython --profile myprofile
     # and
     $> ipython --profile='myprofile'
     # are equivalent to
     $> ipython --BaseIPythonApplication.profile='myprofile'
 
 Flags
------
+*****
 
 Applications can also be passed **flags**. Flags are options that take no
 arguments. They are simply wrappers for
 setting one or more configurables with predefined values, often True/False.
 
 For instance:
 
 .. code-block:: bash
 
     $> ipcontroller --debug
     # is equivalent to
     $> ipcontroller --Application.log_level=DEBUG
     # and
     $> ipython --pylab
     # is equivalent to
     $> ipython --pylab=auto
     # or
     $> ipython --no-banner
     # is equivalent to
     $> ipython --TerminalIPythonApp.display_banner=False
 
 Subcommands
-***********
+-----------
 
 
 Some IPython applications have **subcommands**. Subcommands are modeled after
 :command:`git`, and are called with the form :command:`command subcommand
 [...args]`.  Currently, the QtConsole is a subcommand of terminal IPython:
 
 .. code-block:: bash
 
     $> ipython qtconsole --profile=myprofile
 
 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
 stop, engines).
 
 .. code-block:: bash
 
     $> ipcluster start --profile=myprofile --n=4
 
 
 To see a list of the available aliases, flags, and subcommands for an IPython application, simply pass ``-h`` or ``--help``.  And to see the full list of configurable options (*very* long), pass ``--help-all``.
 
 
 Design requirements
 ===================
 
 Here are the main requirements we wanted our configuration system to have:
 
 * Support for hierarchical configuration information.
 
 * Full integration with command line option parsers.  Often, you want to read
   a configuration file, but then override some of the values with command line
   options.  Our configuration system automates this process and allows each
   command line option to be linked to a particular attribute in the 
   configuration hierarchy that it will override.
 
 * Configuration files that are themselves valid Python code. This accomplishes
   many things. First, it becomes possible to put logic in your configuration
   files that sets attributes based on your operating system, network setup,
   Python version, etc. Second, Python has a super simple syntax for accessing
   hierarchical data structures, namely regular attribute access
   (``Foo.Bar.Bam.name``). Third, using Python makes it easy for users to
   import configuration attributes from one configuration file to another.
   Fourth, even though Python is dynamically typed, it does have types that can
   be checked at runtime. Thus, a ``1`` in a config file is the integer '1',
   while a ``'1'`` is a string.
 
 * A fully automated method for getting the configuration information to the
   classes that need it at runtime. Writing code that walks a configuration
   hierarchy to extract a particular attribute is painful. When you have
   complex configuration information with hundreds of attributes, this makes
   you want to cry.
 
 * Type checking and validation that doesn't require the entire configuration
   hierarchy to be specified statically before runtime. Python is a very
   dynamic language and you don't always know everything that needs to be
   configured when a program starts.
 
 
 .. _`XDG Base Directory`: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

docs/source/interactive/reference.txt

@@ -1,1150 +1,1150 b''
 =================
 IPython reference
 =================
 
 .. _command_line_options:
 
 Command-line usage
 ==================
 
 You start IPython with the command::
 
     $ ipython [options] files
 
 .. note::
 
   For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
 
 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 ipython_config.py. 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 configuration files for details on those. There are separate configuration 
 files for each profile, and the files look like "ipython_config.py" or 
 "ipython_config_<frontendname>.py".  Profile directories look like 
 "profile_profilename" and are typically installed in the IPYTHONDIR directory.
 For Linux users, this will be $HOME/.config/ipython, and for other users it 
 will be $HOME/.ipython.  For Windows users, $HOME resolves to C:\\Documents and
 Settings\\YourUserName in most instances.
 
 
 Eventloop integration
 ---------------------
 
 Previously IPython had command line options for controlling GUI event loop
 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
 version 0.11, these have been removed. Please see the new ``%gui``
 magic command or :ref:`this section <gui_support>` for details on the new
 interface, or specify the gui at the commandline::
 
     $ ipython --gui=qt
 
 
 Command-line Options
 --------------------
 
 To see the options IPython accepts, use ``ipython --help`` (and you probably
 should run the output through a pager such as ``ipython --help | less`` for
 more convenient reading).  This shows all the options that have a single-word
 alias to control them, but IPython lets you configure all of its objects from
 the command-line by passing the full class name and a corresponding value; type
 ``ipython --help-all`` to see this full list.  For example::
 
   ipython --pylab qt
 
 is equivalent to::
 
   ipython --TerminalIPythonApp.pylab='qt'
 
 Note that in the second form, you *must* use the equal sign, as the expression
 is evaluated as an actual Python assignment.  While in the above example the
 short form is more convenient, only the most common options have a short form,
 while any configurable variable in IPython can be set at the command-line by
 using the long form.  This long form is the same syntax used in the
 configuration files, if you want to set these options permanently.
 
 
 Interactive use
 ===============
 
 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.
 
 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
 only the rest of the current line, but all lines below them as well, in the
 current execution block.  Cell magics can in fact make arbitrary modifications
 to the input they receive, which need not even be valid Python code at all.
 They receive the whole block as a single string.
 
 As a line magic example, the ``%cd`` magic works just like the OS command of
 the same name::
 
       In [8]: %cd
       /home/fperez
 
 The following uses the builtin ``timeit`` in cell mode::
   
   In [10]: %%timeit x = range(10000)
       ...: min(x)
       ...: max(x)
       ...: 
   1000 loops, best of 3: 438 us per loop
 
 In this case, ``x = range(10000)`` is called as the line argument, and the
 block with ``min(x)`` and ``max(x)`` is called as the cell body.  The
 ``timeit`` magic receives both.
   
 If you have 'automagic' enabled (as it by default), you don't need to type in
 the single ``%`` explicitly for line magics; 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'::
 
       In [9]: cd mydir
       /home/fperez/mydir
 
 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
 calling only works for line magics.
       
 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:
 
 .. sourcecode:: ipython
 
     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 "<ipython-input-3-9fedb3aff56c>", 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, automagic works again
 
     In [6]: cd ipython
 
     /home/fperez/ipython
 
 Defining your own magics
-~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++
 
 There are two main ways to define your own magic functions: from standalone
 functions and by inheriting from a base class provided by IPython:
 :class:`IPython.core.magic.Magics`.  Below we show code you can place in a file
 that you load from your configuration, such as any file in the ``startup``
 subdirectory of your default IPython profile.
 
 First, let us see the simplest case.  The following shows how to create a line
 magic, a cell one and one that works in both modes, using just plain functions:
 
 .. sourcecode:: python
 
     from IPython.core.magic import (register_line_magic, register_cell_magic,
                                     register_line_cell_magic)
 		
     @register_line_magic
     def lmagic(line):
         "my line magic"
 	return line
 
     @register_cell_magic
     def cmagic(line, cell):
         "my cell magic"
         return line, cell
 
     @register_line_cell_magic
     def lcmagic(line, cell=None):
         "Magic that works both as %lcmagic and as %%lcmagic"
 	if cell is None:
 	    print "Called as line magic"
 	    return line
 	else:
 	    print "Called as cell magic"
             return line, cell
 
     # We delete these to avoid name conflicts for automagic to work
     del lmagic, lcmagic
 
 
 You can also create magics of all three kinds by inheriting from the
 :class:`IPython.core.magic.Magics` class.  This lets you create magics that can
 potentially hold state in between calls, and that have full access to the main
 IPython object:
     
 .. sourcecode:: python
 		
     # This code can be put in any Python module, it does not require IPython
     # itself to be running already.  It only creates the magics subclass but
     # doesn't instantiate it yet.
     from IPython.core.magic import (Magics, magics_class, line_magic,
                                     cell_magic, line_cell_magic)
 
     # The class MUST call this class decorator at creation time
     @magics_class
     class MyMagics(Magics):
 
         @line_magic
         def lmagic(self, line):
             "my line magic"
             print "Full access to the main IPython object:", self.shell
             print "Variables in the user namespace:", self.shell.user_ns.keys()
             return line
 
         @cell_magic
         def cmagic(self, line, cell):
             "my cell magic"
             return line, cell
 
         @line_cell_magic
         def lcmagic(self, line, cell=None):
             "Magic that works both as %lcmagic and as %%lcmagic"
             if cell is None:
                 print "Called as line magic"
                 return line
             else:
                 print "Called as cell magic"
                 return line, cell
 
 
     # In order to actually use these magics, you must register them with a
     # running IPython.  This code must be placed in a file that is loaded once
     # IPython is up and running:
     ip = get_ipython()
     # You can register the class itself without instantiating it.  IPython will
     # call the default constructor on it.
     ip.register_magics(MyMagics)
 
 If you want to create a class with a different constructor that holds
 additional state, then you should always call the parent constructor and
 instantiate the class yourself before registration:
 
 .. sourcecode:: python
 		
     @magics_class
     class StatefulMagics(Magics):
         "Magics that hold additional state"
 	
         def __init__(self, shell, data):
             # You must call the parent constructor
             super(StatefulMagics, self).__init__(shell)
             self.data = data
         
         # etc...
 
     # This class must then be registered with a manually created instance,
     # since its constructor has different arguments from the default:
     ip = get_ipython()
     magics = StatefulMagics(ip, some_data)
     ip.register_magics(magics)
     
 
 In earlier versions, IPython had an API for the creation of line magics (cell
 magics did not exist at the time) that required you to create functions with a
 method-looking signature and to manually pass both the function and the name.
 While this API is no longer recommended, it remains indefinitely supported for
 backwards compatibility purposes.  With the old API, you'd create a magic as
 follows:
 
 .. sourcecode:: python
 
     def func(self, line):
         print "Line magic called with line:", line
 	print "IPython object:", self.shell
 
     ip = get_ipython()
     # Declare this function as the magic %mycommand
     ip.define_magic('mycommand', func)
 
 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 :ref:`below <dynamic_object_info>` for
 information on the '?' system) to get information about any particular magic
 function you are interested in.
 
 The API documentation for the :mod:`IPython.core.magic` module contains the full
 docstrings of all currently available magic commands.
 
 
 Access to the standard Python help
 ----------------------------------
 
 Simply type ``help()`` to access Python's standard help system. You can
 also type ``help(object)`` for information about a given object, or
 ``help('keyword')`` for information on a keyword. You may need to configure your
 PYTHONDOCS environment variable 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 (e.g. function signatures) they get
 snipped in the center for brevity. This system gives access variable types and
 values, docstrings, function prototypes and other useful information.
 
 If the information will not fit in the terminal, it is displayed in a pager
 (``less`` if available, otherwise a basic internal pager).
 
 Typing ``??word`` or ``word??`` gives access to the full information, including
 the source code where possible. Long strings are not snipped.
 
 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 (``%function_name?``);
 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 call signature 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``) work on object attributes, as well as
 directly on variables. For example, after doing ``import os``, you can use
 ``os.path.abspath??``.
 
 .. _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/profile_<name>/history.sqlite. 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
 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
 to). Adding the following lines to your :file:`.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::
 
     Setting the above indents will cause problems with unicode text entry in
     the terminal.
 
 .. warning::
 
     Autoindent 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 :file:`ipython_config.py` file
     (set TerminalInteractiveShell.autoindent=False).
     
     If you want to paste multiple lines in the terminal, it is recommended that
     you use ``%paste``.
 
 
 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 configuration file (note
 that these options can not be specified at the command line):
 
     * **readline_parse_and_bind**: this holds a list of strings 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.
 
 You will find the default values in your configuration file.
 
 
 Session logging and restoring
 -----------------------------
 
 You can log all input from a session either by starting IPython with the
 command line switch ``--logfile=foo.py`` (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 by running them as scripts 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 'ipython_log.py' in your
 current working 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
 --------------------------------
 
 You can assign the result of a system command to a Python variable with the
 syntax ``myfiles = !ls``. This gets machine readable output from stdout 
 (e.g. without colours), and splits on newlines. To explicitly get this sort of
 output without assigning to a variable, use two exclamation marks (``!!ls``) or
 the ``%sx`` magic command.
 
 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
 See :ref:`string_lists` for details.
 
 IPython also allows you to expand the value of python variables when
 making system calls. Wrap variables or expressions in {braces}::
 
     In [1]: pyvar = 'Hello world' 
     In [2]: !echo "A python variable: {pyvar}"  
     A python variable: Hello world
     In [3]: import math
     In [4]: x = 8
     In [5]: !echo {math.factorial(x)}
     40320
 
 For simple cases, you can alternatively prepend $ to a variable name::
 
     In [6]: !echo $sys.argv  
     [/home/fperez/usr/bin/ipython]
     In [7]: !echo "A system variable: $$HOME"  # Use $$ for literal $
     A system variable: /home/fperez
 
 System command aliases
 ----------------------
 
 The %alias magic function allows 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  
     ERROR: Alias <parts> requires 2 arguments, 1 given.
 
 If called with no parameters, %alias prints the table of currently
 defined aliases.
 
 The %rehashx magic allows you to load your entire $PATH as
 ipython aliases. See its docstring for further details.
 
 
 .. _dreload:
 
 Recursive reload
 ----------------
 
 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
 module: changes made to any of its dependencies will be reloaded without
 having to exit. To start using it, do::
 
     from IPython.lib.deepreload import reload as dreload
 
 
 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 system
 --------------------
 
 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, _ii, _iii: store previous, next previous and next-next previous inputs.
 * In, _ih : a list of all inputs; _ih[n] is the input from line n. 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), so ``_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.
 
 You can also re-execute multiple lines of input easily by using the
 magic %rerun or %macro functions. The macro system also allows you to re-execute
 previous lines which include magic function calls (which require special
 processing). Type %macro? 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.
 
 You can also search ('grep') through your history by typing 
 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
 etc. You can bring history entries listed by '%hist -g' up for editing
 with the %recall command, or run them immediately with %rerun.
 
 .. _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 variables are also 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 configuration
 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
 conveniently 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)::
 
     In [1]: callable_ob arg1, arg2, arg3
     ------> callable_ob(arg1, arg2, arg3)
 
 You can force automatic parentheses by using '/' as the first character
 of a line. For example::
 
     In [2]: /globals # becomes 'globals()'
 
 Note that the '/' MUST be the first character on the line! This won't work::
 
     In [3]: 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 [4]: zip (1,2,3),(4,5,6) # won't work
 
 but this will work::
 
     In [5]: /zip (1,2,3),(4,5,6) 
     ------> zip ((1,2,3),(4,5,6))  
     Out[5]: [(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 [6]: 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::
 
     In [1]: ,my_function /home/me  # becomes my_function("/home/me")
 
 If you use ';' the whole argument is quoted as a single string, while ',' splits
 on whitespace::
 
     In [2]: ,my_function a b c    # becomes my_function("a","b","c")
 
     In [3]: ;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::
 
     In [4]: 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 the following code at
 the end of that file, then IPython will be your working environment anytime you
 start Python::
 
     from IPython.frontend.terminal.ipapp import launch_new_instance
     launch_new_instance()
     raise SystemExit
 
 The ``raise SystemExit`` is needed to exit Python 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.
 
 .. note::
 
   At present, trying to embed IPython from inside IPython causes problems. Run
   the code samples below outside IPython.
 
 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 import embed
 
     embed() # this call anywhere in your program will start IPython
 
 .. note::
 
     As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
     etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
     It should function just the same as regular embed, but you connect
     an external frontend rather than IPython starting up in the local
     terminal.
 
 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 :mod:`~IPython.frontend.terminal.embed` 
 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:
 
 .. literalinclude:: ../../../examples/core/example-embed.py
     :language: python
 
 Once you understand how the system functions, you can use the following
 code fragments in your programs which are ready for cut and paste:
 
 .. literalinclude:: ../../../examples/core/example-embed-short.py
     :language: python
 
 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 config 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 pdb will automatically 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
     from IPython.core import ultratb
     sys.excepthook = 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_with_prompts:
 
 Pasting of code starting with Python or IPython prompts
 -------------------------------------------------------
 
-IPython is smart enough to filter  out input prompts, be they plain Python ones
-(``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``).  You can
+IPython is smart enough to filter out input prompts, be they plain Python ones
+(``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``).  You can
 therefore copy and paste from existing interactive sessions without worry.
 
 The following is a 'screenshot' of how things work, copying an example from the
 standard Python tutorial::
 
     In [1]: >>> # Fibonacci series:
 
     In [2]: ... # the sum of two elements defines the next
 
     In [3]: ... a, b = 0, 1
 
     In [4]: >>> while b < 10:
        ...:     ...     print b
        ...:     ...     a, b = b, a+b
        ...:     
     1
     1
     2
     3
     5
     8
 
 And pasting from IPython sessions works equally well::
 
     In [1]: In [5]: def f(x):
        ...:        ...:     "A simple function"
        ...:        ...:     return x**2
        ...:    ...: 
 
     In [2]: f(3)
     Out[2]: 9
 
 .. _gui_support:
 
 GUI event loop support
 ======================
 
 .. versionadded:: 0.11
     The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
 
 IPython has excellent support for working interactively with Graphical User
 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
 is extremely robust compared to our previous thread-based version. The
 advantages of this are:
 
 * GUIs can be enabled and disabled dynamically at runtime.
 * The active GUI can be switched dynamically at runtime.
 * In some cases, multiple GUIs can run simultaneously with no problems.
 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing 
   all of these things.
 
 For users, enabling GUI event loop integration is simple.  You simple use the
 ``%gui`` magic as follows::
 
     %gui [GUINAME]
 
 With no arguments, ``%gui`` removes all GUI support.  Valid ``GUINAME``
 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
 
 Thus, to use wxPython interactively and create a running :class:`wx.App`
 object, do::
 
     %gui wx
 
 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
 see :ref:`this section <matplotlib_support>`.
 
 For developers that want to use IPython's GUI event loop integration in the
 form of a library, these capabilities are exposed in library form in the
 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
 Interested developers should see the module docstrings for more information,
 but there are a few points that should be mentioned here.
 
 First, the ``PyOSInputHook`` approach only works in command line settings 
 where readline is activated.  The integration with various eventloops
 is handled somewhat differently (and more simply) when using the standalone
 kernel, as in the qtconsole and notebook.
 
 Second, when using the ``PyOSInputHook`` approach, a GUI application should
 *not* start its event loop. Instead all of this is handled by the
 ``PyOSInputHook``. This means that applications that are meant to be used both
 in IPython and as standalone apps need to have special code to detects how the
 application is being run. We highly recommend using IPython's support for this.
 Since the details vary slightly between toolkits, we point you to the various
 examples in our source directory :file:`docs/examples/lib` that demonstrate
 these capabilities.
 
 Third, unlike previous versions of IPython, we no longer "hijack" (replace
 them with no-ops) the event loops. This is done to allow applications that
 actually need to run the real event loops to do so. This is often needed to
 process pending events at critical points.
 
 Finally, we also have a number of examples in our source directory
 :file:`docs/examples/lib` that demonstrate these capabilities.
 
 PyQt and PySide
 ---------------
 
 .. attempt at explanation of the complete mess that is Qt support
 
 When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
 PyQt4 or PySide.  There are three options for configuration here, because
 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
 Python 2, and the more natural v2, which is the only API supported by PySide.
 v2 is also the default for PyQt4 on Python 3.  IPython's code for the QtConsole
 uses v2, but you can still use any interface in your code, since the
 Qt frontend is in a different process.
 
 The default will be to import PyQt4 without configuration of the APIs, thus
 matching what most applications would expect. It will fall back of PySide if
 PyQt4 is unavailable.
 
 If specified, IPython will respect the environment variable ``QT_API`` used
 by ETS.  ETS 4.0 also works with both PyQt4 and PySide, but it requires
 PyQt4 to use its v2 API.  So if ``QT_API=pyside`` PySide will be used,
 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
 
 If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
 will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
 the 'backend.qt4' rcParam.  If matplotlib is version 1.0.1 or older, then
 IPython will always use PyQt4 without setting the v2 APIs, since neither v2
 PyQt nor PySide work.
 
 .. warning::
 
     Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
     to work with IPython's qt integration, because otherwise PyQt4 will be
     loaded in an incompatible mode.
     
     It also means that you must *not* have ``QT_API`` set if you want to
     use ``--gui=qt`` with code that requires PyQt4 API v1.
 
 
 .. _matplotlib_support:
 
 Plotting with matplotlib
 ========================
 
 `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
 can produce plots on screen using a variety of GUI toolkits, including Tk,
 PyGTK, PyQt4 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.
 
 To start IPython with matplotlib support, use the ``--pylab`` switch.  If no
 arguments are given, IPython will automatically detect your choice of
 matplotlib backend.  You can also request a specific backend with ``--pylab
 backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', 'osx'.
 In the web notebook and Qt console, 'inline' is also a valid backend value,
 which produces static figures inlined inside the application window instead of
 matplotlib's interactive figures that live in separate windows.
 
 .. _Matplotlib: http://matplotlib.sourceforge.net
 
 .. _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:
 
 .. literalinclude:: ../../../examples/lib/example-demo.py
     :language: python
 
 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.lib.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.lib import demo
 
     demo?
 
 Limitations: It is important to note that these demos are limited to
 fairly simple uses. In particular, you cannot break up sections within
 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, see :func:`IPython.embed` for details.
 

docs/source/whatsnew/version0.11.txt

@@ -1,765 +1,765 b''
 =============
  0.11 Series
 =============
 
 Release 0.11
 ============
 
 IPython 0.11 is a *major* overhaul of IPython, two years in the making.  Most
 of the code base has been rewritten or at least reorganized, breaking backward
 compatibility with several APIs in previous versions.  It is the first major
 release in two years, and probably the most significant change to IPython since
 its inception.  We plan to have a relatively quick succession of releases, as
 people discover new bugs and regressions.  Once we iron out any significant
 bugs in this process and settle down the new APIs, this series will become
 IPython 1.0.  We encourage feedback now on the core APIs, which we hope to
 maintain stable during the 1.0 series.
 
 Since the internal APIs have changed so much, projects using IPython as a
 library (as opposed to end-users of the application) are the most likely to
 encounter regressions or changes that break their existing use patterns.  We
 will make every effort to provide updated versions of the APIs to facilitate
 the transition, and we encourage you to contact us on the `development mailing
 list`__ with questions and feedback.
 
 .. __: http://mail.scipy.org/mailman/listinfo/ipython-dev
 
 Chris Fonnesbeck recently wrote an `excellent post`__ that highlights some of
 our major new features, with examples and screenshots.  We encourage you to
 read it as it provides an illustrated, high-level overview complementing the
 detailed feature breakdown in this document.
 
 .. __: http://fonnesbeck.calepin.co/innovations-in-ipython.html
 
 A quick summary of the major changes (see below for details):
 
 * **Standalone Qt console**: a new rich console has been added to IPython,
   started with `ipython qtconsole`.  In this application we have tried to
   retain the feel of a terminal for fast and efficient workflows, while adding
   many features that a line-oriented terminal simply can not support, such as
   inline figures, full multiline editing with syntax highlighting, graphical
   tooltips for function calls and much more.  This development was sponsored by
   `Enthought Inc.`__. See :ref:`below <qtconsole_011>` for details.
 
 .. __: http://enthought.com
 
 * **High-level parallel computing with ZeroMQ**. Using the same architecture
   that our Qt console is based on, we have completely rewritten our high-level
   parallel computing machinery that in prior versions used the Twisted
   networking framework.  While this change will require users to update their
   codes, the improvements in performance, memory control and internal
   consistency across our codebase convinced us it was a price worth paying.  We
   have tried to explain how to best proceed with this update, and will be happy
   to answer questions that may arise.  A full tutorial describing these
   features `was presented at SciPy'11`__, more details :ref:`below
   <parallel_011>`.
 
 .. __: http://minrk.github.com/scipy-tutorial-2011
 
 * **New model for GUI/plotting support in the terminal**.  Now instead of the
   various `-Xthread` flags we had before, GUI support is provided without the
   use of any threads, by directly integrating GUI event loops with Python's
   `PyOS_InputHook` API.  A new command-line flag `--gui` controls GUI support,
   and it can also be enabled after IPython startup via the new `%gui` magic.
   This requires some changes if you want to execute GUI-using scripts inside
   IPython, see :ref:`the GUI support section <gui_support>` for more details.
 
 * **A two-process architecture.** The Qt console is the first use of a new
   model that splits IPython between a kernel process where code is executed and
   a client that handles user interaction.  We plan on also providing terminal
   and web-browser based clients using this infrastructure in future releases.
   This model allows multiple clients to interact with an IPython process
   through a :ref:`well-documented messaging protocol <messaging>` using the
   ZeroMQ networking library.
 
 * **Refactoring.** the entire codebase has been refactored, in order to make it
   more modular and easier to contribute to.  IPython has traditionally been a
   hard project to participate because the old codebase was very monolithic.  We
   hope this (ongoing) restructuring will make it easier for new developers to
   join us.
 
 * **Vim integration**. Vim can be configured to seamlessly control an IPython
   kernel, see the files in :file:`docs/examples/vim` for the full details.
   This work was done by Paul Ivanov, who prepared a nice `video
   demonstration`__ of the features it provides.
 
 .. __: http://pirsquared.org/blog/2011/07/28/vim-ipython/
   
 * **Integration into Microsoft Visual Studio**. Thanks to the work of the
   Microsoft `Python Tools for Visual Studio`__ team, this version of IPython
   has been integrated into Microsoft Visual Studio's Python tools open source
   plug-in.  `Details below`_
 
 .. __: http://pytools.codeplex.com
 .. _details below: ms_visual_studio_011_
 
 * **Improved unicode support**. We closed many bugs related to unicode input.
 
 * **Python 3**. IPython now runs on Python 3.x. See :ref:`python3_011` for
   details.
 
 * **New profile model**. Profiles are now directories that contain all relevant
   infromation for that session, and thus better isolate IPython use-cases.
 
 * **SQLite storage for history**. All history is now stored in a SQLite
   database, providing support for multiple simultaneous sessions that won't
   clobber each other as well as the ability to perform queries on all stored
   data.
 
 * **New configuration system**. All parts of IPython are now configured via a
   mechanism inspired by the Enthought Traits library.  Any configurable element
   can have its attributes set either via files that now use real Python syntax
   or from the command-line.
 
 * **Pasting of code with prompts**. IPython now intelligently strips out input
   prompts , be they plain Python ones (``>>>`` and ``...``) or IPython ones
-  (``In [N]:`` and `` ...:``).  More details :ref:`here <pasting_with_prompts>`.
+  (``In [N]:`` and ``...:``).  More details :ref:`here <pasting_with_prompts>`.
   
 
 Authors and support
 -------------------
 
 Over 60 separate authors have contributed to this release, see :ref:`below
 <credits_011>` for a full list.  In particular, we want to highlight the
 extremely active participation of two new core team members: Evan Patterson
 implemented the Qt console, and Thomas Kluyver started with our Python 3 port
 and by now has made major contributions to just about every area of IPython.
 
 We are also grateful for the support we have received during this development
 cycle from several institutions:
 
 - `Enthought Inc`__ funded the development of our new Qt console, an effort that
   required developing major pieces of underlying infrastructure, which now
   power not only the Qt console but also our new parallel machinery.  We'd like
   to thank Eric Jones and Travis Oliphant for their support, as well as Ilan
   Schnell for his tireless work integrating and testing IPython in the
   `Enthought Python Distribution`_.
 
 .. __: http://enthought.com
 .. _Enthought Python Distribution: http://www.enthought.com/products/epd.php
 
 - Nipy/NIH: funding via the `NiPy project`__ (NIH grant 5R01MH081909-02) helped
   us jumpstart the development of this series by restructuring the entire
   codebase two years ago in a way that would make modular development and
   testing more approachable.  Without this initial groundwork, all the new
   features we have added would have been impossible to develop.
 
 .. __: http://nipy.org
 
 - Sage/NSF: funding via the grant `Sage: Unifying Mathematical Software for
   Scientists, Engineers, and Mathematicians`__ (NSF grant DMS-1015114)
   supported a meeting in spring 2011 of several of the core IPython developers
   where major progress was made integrating the last key pieces leading to this
   release.
 
 .. __: http://modular.math.washington.edu/grants/compmath09
 
 - Microsoft's team working on `Python Tools for Visual Studio`__ developed the 
   integraton of IPython into the Python plugin for Visual Studio 2010.
 
 .. __: http://pytools.codeplex.com
 
 - Google Summer of Code: in 2010, we had two students developing prototypes of
   the new machinery that is now maturing in this release: `Omar Zapata`_ and
   `Gerardo Gutiérrez`_.
 
 .. _Omar Zapata: http://ipythonzmq.blogspot.com/2010/08/ipython-zmq-status.html
 .. _Gerardo Gutiérrez: http://ipythonqt.blogspot.com/2010/04/ipython-qt-interface-gsoc-2010-proposal.html>
 
 
 Development summary: moving to Git and Github
 ---------------------------------------------
 
 In April 2010, after `one breakage too many with bzr`__, we decided to move our
 entire development process to Git and Github.com.  This has proven to be one of
 the best decisions in the project's history, as the combination of git and
 github have made us far, far more productive than we could be with our previous
 tools.  We first converted our bzr repo to a git one without losing history,
 and a few weeks later ported all open Launchpad bugs to github issues with
 their comments mostly intact (modulo some formatting changes).  This ensured a
 smooth transition where no development history or submitted bugs were lost.
 Feel free to use our little Launchpad to Github issues `porting script`_ if you
 need to make a similar transition.
 
 .. __: http://mail.scipy.org/pipermail/ipython-dev/2010-April/005944.html
 .. _porting script: https://gist.github.com/835577
 
 These simple statistics show how much work has been done on the new release, by
 comparing the current code to the last point it had in common with the 0.10
 series.  A huge diff and ~2200 commits make up this cycle::
 
     git diff $(git merge-base 0.10.2 HEAD)  | wc -l
     288019
 
     git log $(git merge-base 0.10.2 HEAD)..HEAD --oneline | wc -l
     2200
 
 Since our move to github, 511 issues were closed, 226 of which were pull
 requests and 285 regular issues (:ref:`a full list with links
 <issues_list_011>` is available for those interested in the details).  Github's
 pull requests are a fantastic mechanism for reviewing code and building a
 shared ownership of the project, and we are making enthusiastic use of it.
 
 .. Note::
 
    This undercounts the number of issues closed in this development cycle,
    since we only moved to github for issue tracking in May 2010, but we have no
    way of collecting statistics on the number of issues closed in the old
    Launchpad bug tracker prior to that.
 
    
 .. _qtconsole_011:
 
 Qt Console
 ----------
 
 IPython now ships with a Qt application that feels very much like a terminal,
 but is in fact a rich GUI that runs an IPython client but supports inline
 figures, saving sessions to PDF and HTML, multiline editing with syntax
 highlighting, graphical calltips and much more:
 
 .. figure:: ../_static/qtconsole.png
     :width: 400px
     :alt: IPython Qt console with embedded plots
     :align: center
     :target: ../_static/qtconsole.png
 
     The Qt console for IPython, using inline matplotlib plots.
 
 We hope that many projects will embed this widget, which we've kept
 deliberately very lightweight, into their own environments.  In the future we
 may also offer a slightly more featureful application (with menus and other GUI
 elements), but we remain committed to always shipping this easy to embed
 widget.
 
 See the :ref:`Qt console section <qtconsole>` of the docs for a detailed
 description of the console's features and use.
 
 
 .. _parallel_011:
 
 High-level parallel computing with ZeroMQ
 -----------------------------------------
 
 We have completely rewritten the Twisted-based code for high-level parallel
 computing to work atop our new ZeroMQ architecture.  While we realize this will
 break compatibility for a number of users, we hope to make the transition as
 easy as possible with our docs, and we are convinced the change is worth it.
 ZeroMQ provides us with much tighter control over memory, higher performance,
 and its communications are impervious to the Python Global Interpreter Lock
 because they take place in a system-level C++ thread.  The impact of the GIL in
 our previous code was something we could simply not work around, given that
 Twisted is itself a Python library.  So while Twisted is a very capable
 framework, we think ZeroMQ fits our needs much better and we hope you will find
 the change to be a significant improvement in the long run.
 
 Our manual contains :ref:`a full description of how to use IPython for parallel
 computing <parallel_overview>`, and the `tutorial`__ presented by Min
 Ragan-Kelley at the SciPy 2011 conference provides a hands-on complement to the
 reference docs.
 
 .. __: http://minrk.github.com/scipy-tutorial-2011
 
 
 Refactoring
 -----------
 
 As of this release, a signifiant portion of IPython has been refactored.  This
 refactoring is founded on a number of new abstractions.  The main new classes
 that implement these abstractions are:
 
 * :class:`IPython.utils.traitlets.HasTraits`.
 * :class:`IPython.config.configurable.Configurable`.
 * :class:`IPython.config.application.Application`.
 * :class:`IPython.config.loader.ConfigLoader`.
 * :class:`IPython.config.loader.Config`
 
 We are still in the process of writing developer focused documentation about
 these classes, but for now our :ref:`configuration documentation
 <config_overview>` contains a high level overview of the concepts that these
 classes express.
 
 The biggest user-visible change is likely the move to using the config system
 to determine the command-line arguments for IPython applications. The benefit
 of this is that *all* configurable values in IPython are exposed on the
 command-line, but the syntax for specifying values has changed. The gist is
 that assigning values is pure Python assignment.  Simple flags exist for
 commonly used options, these are always prefixed with '--'.
 
 The IPython command-line help has the details of all the options (via
 ``ipythyon --help``), but a simple example should clarify things; the ``pylab``
 flag can be used to start in pylab mode with the qt4 backend::
 
   ipython --pylab=qt
 
 which is equivalent to using the fully qualified form::
 
   ipython --TerminalIPythonApp.pylab=qt
 
 The long-form options can be listed via ``ipython --help-all``.
 
 
 ZeroMQ architecture
 -------------------
 
 There is a new GUI framework for IPython, based on a client-server model in
 which multiple clients can communicate with one IPython kernel, using the
 ZeroMQ messaging framework. There is already a Qt console client, which can
 be started by calling ``ipython qtconsole``. The protocol is :ref:`documented
 <messaging>`.
 
 The parallel computing framework has also been rewritten using ZMQ. The
 protocol is described :ref:`here <parallel_messages>`, and the code is in the
 new :mod:`IPython.parallel` module.
 
 .. _python3_011:
 
 Python 3 support
 ----------------
 
 A Python 3 version of IPython has been prepared. For the time being, this is
 maintained separately and updated from the main codebase. Its code can be found
 `here <https://github.com/ipython/ipython-py3k>`_. The parallel computing
 components are not perfect on Python3, but most functionality appears to be
 working.  As this work is evolving quickly, the best place to find updated
 information about it is our `Python 3 wiki page`__.
 
 .. __: http://wiki.ipython.org/index.php?title=Python_3
 
 
 Unicode
 -------
 
 Entering non-ascii characters in unicode literals (``u"€ø"``) now works
 properly on all platforms. However, entering these in byte/string literals
 (``"€ø"``) will not work as expected on Windows (or any platform where the
 terminal encoding is not UTF-8, as it typically is for Linux & Mac OS X). You
 can use escape sequences (``"\xe9\x82"``) to get bytes above 128, or use
 unicode literals and encode them. This is a limitation of Python 2 which we
 cannot easily work around.
 
 .. _ms_visual_studio_011:
 
 Integration with Microsoft Visual Studio
 ----------------------------------------
 
 IPython can be used as the interactive shell in the `Python plugin for
 Microsoft Visual Studio`__, as seen here:
 
 .. figure:: ../_static/ms_visual_studio.png
     :width: 500px
     :alt: IPython console embedded in Microsoft Visual Studio.
     :align: center
     :target: ../_static/ms_visual_studio.png
 
     IPython console embedded in Microsoft Visual Studio.
 
 The Microsoft team developing this currently has a release candidate out using
 IPython 0.11. We will continue to collaborate with them to ensure that as they
 approach their final release date, the integration with IPython remains smooth.
 We'd like to thank Dino Viehland and Shahrokh Mortazavi for the work they have
 done towards this feature, as well as Wenming Ye for his support of our WinHPC
 capabilities.
 
 .. __: http://pytools.codeplex.com
 
 
 Additional new features
 -----------------------
 
 * Added ``Bytes`` traitlet, removing ``Str``.  All 'string' traitlets should
   either be ``Unicode`` if a real string, or ``Bytes`` if a C-string. This
   removes ambiguity and helps the Python 3 transition.
 
 * New magic ``%loadpy`` loads a python file from disk or web URL into
   the current input buffer.
 
 * New magic ``%pastebin`` for sharing code via the 'Lodge it' pastebin.
 
 * New magic ``%precision`` for controlling float and numpy pretty printing.
 
 * IPython applications initiate logging, so any object can gain access to
   a the logger of the currently running Application with:
 
 .. sourcecode:: python
 
     from IPython.config.application import Application
     logger = Application.instance().log
 
 * You can now get help on an object halfway through typing a command. For
   instance, typing ``a = zip?`` shows the details of :func:`zip`. It also
   leaves the command at the next prompt so you can carry on with it.
 
 * The input history is now written to an SQLite database. The API for
   retrieving items from the history has also been redesigned.
 
 * The :mod:`IPython.extensions.pretty` extension has been moved out of
   quarantine and fully updated to the new extension API.
 
 * New magics for loading/unloading/reloading extensions have been added:
   ``%load_ext``, ``%unload_ext`` and ``%reload_ext``.
 
 * The configuration system and configuration files are brand new. See the
   configuration system :ref:`documentation <config_index>` for more details.
 
 * The :class:`~IPython.core.interactiveshell.InteractiveShell` class is now a
   :class:`~IPython.config.configurable.Configurable` subclass and has traitlets
   that determine the defaults and runtime environment. The ``__init__`` method
   has also been refactored so this class can be instantiated and run without
   the old :mod:`ipmaker` module.
 
 * The methods of :class:`~IPython.core.interactiveshell.InteractiveShell` have
   been organized into sections to make it easier to turn more sections
   of functionality into components.
 
 * The embedded shell has been refactored into a truly standalone subclass of
   :class:`InteractiveShell` called :class:`InteractiveShellEmbed`.  All
   embedding logic has been taken out of the base class and put into the 
   embedded subclass.
 
 * Added methods of :class:`~IPython.core.interactiveshell.InteractiveShell` to
   help it cleanup after itself. The :meth:`cleanup` method controls this. We
   couldn't do this in :meth:`__del__` because we have cycles in our object
   graph that prevent it from being called.
 
 * Created a new module :mod:`IPython.utils.importstring` for resolving
   strings like ``foo.bar.Bar`` to the actual class.
 
 * Completely refactored the :mod:`IPython.core.prefilter` module into
   :class:`~IPython.config.configurable.Configurable` subclasses. Added a new
   layer into the prefilter system, called "transformations" that all new
   prefilter logic should use (rather than the older "checker/handler"
   approach).
 
 * Aliases are now components (:mod:`IPython.core.alias`).
 
 * New top level :func:`~IPython.frontend.terminal.embed.embed` function that can
   be called to embed IPython at any place in user's code. On the first call it
   will create an :class:`~IPython.frontend.terminal.embed.InteractiveShellEmbed`
   instance and call it. In later calls, it just calls the previously created
   :class:`~IPython.frontend.terminal.embed.InteractiveShellEmbed`.
 
 * Created a configuration system (:mod:`IPython.config.configurable`) that is
   based on :mod:`IPython.utils.traitlets`. Configurables are arranged into a
   runtime containment tree (not inheritance) that i) automatically propagates
   configuration information and ii) allows singletons to discover each other in
   a loosely coupled manner. In the future all parts of IPython will be
   subclasses of :class:`~IPython.config.configurable.Configurable`. All IPython
   developers should become familiar with the config system.
 
 * Created a new :class:`~IPython.config.loader.Config` for holding
   configuration information. This is a dict like class with a few extras: i)
   it supports attribute style access, ii) it has a merge function that merges
   two :class:`~IPython.config.loader.Config` instances recursively and iii) it
   will automatically create sub-:class:`~IPython.config.loader.Config`
   instances for attributes that start with an uppercase character.
 
 * Created new configuration loaders in :mod:`IPython.config.loader`. These
   loaders provide a unified loading interface for all configuration
   information including command line arguments and configuration files. We
   have two default implementations based on :mod:`argparse` and plain python
   files.  These are used to implement the new configuration system.
 
 * Created a top-level :class:`Application` class in
   :mod:`IPython.core.application` that is designed to encapsulate the starting
   of any basic Python program. An application loads and merges all the
   configuration objects, constructs the main application, configures and
   initiates logging, and creates and configures any :class:`Configurable`
   instances and then starts the application running. An extended
   :class:`BaseIPythonApplication` class adds logic for handling the
   IPython directory as well as profiles, and all IPython entry points
   extend it.
 
 * The :class:`Type` and :class:`Instance` traitlets now handle classes given
   as strings, like ``foo.bar.Bar``. This is needed for forward declarations.
   But, this was implemented in a careful way so that string to class
   resolution is done at a single point, when the parent
   :class:`~IPython.utils.traitlets.HasTraitlets` is instantiated.
 
 * :mod:`IPython.utils.ipstruct` has been refactored to be a subclass of 
   dict.  It also now has full docstrings and doctests.
 
 * Created a Traits like implementation in :mod:`IPython.utils.traitlets`.  This
   is a pure Python, lightweight version of a library that is similar to
   Enthought's Traits project, but has no dependencies on Enthought's code.  We
   are using this for validation, defaults and notification in our new component
   system.  Although it is not 100% API compatible with Enthought's Traits, we
   plan on moving in this direction so that eventually our implementation could
   be replaced by a (yet to exist) pure Python version of Enthought Traits.
 
 * Added a new module :mod:`IPython.lib.inputhook` to manage the integration
   with GUI event loops using `PyOS_InputHook`.  See the docstrings in this
   module or the main IPython docs for details.
 
 * For users, GUI event loop integration is now handled through the new
   :command:`%gui` magic command.  Type ``%gui?`` at an IPython prompt for
   documentation.
 
 * For developers :mod:`IPython.lib.inputhook` provides a simple interface
   for managing the event loops in their interactive GUI applications.
   Examples can be found in our :file:`docs/examples/lib` directory.
 
 Backwards incompatible changes
 ------------------------------
 
 * The Twisted-based :mod:`IPython.kernel` has been removed, and completely
   rewritten as :mod:`IPython.parallel`, using ZeroMQ.
 
 * Profiles are now directories. Instead of a profile being a single config file,
   profiles are now self-contained directories. By default, profiles get their
   own IPython history, log files, and everything. To create a new profile, do
   ``ipython profile create <name>``.
 
 * All IPython applications have been rewritten to use
   :class:`~IPython.config.loader.KeyValueConfigLoader`. This means that
   command-line options have changed. Now, all configurable values are accessible
   from the command-line with the same syntax as in a configuration file.
 
 * The command line options ``-wthread``, ``-qthread`` and
   ``-gthread`` have been removed. Use ``--gui=wx``, ``--gui=qt``, ``--gui=gtk``
   instead.
 
 * The extension loading functions have been renamed to
   :func:`load_ipython_extension` and :func:`unload_ipython_extension`.
 
 * :class:`~IPython.core.interactiveshell.InteractiveShell` no longer takes an
   ``embedded`` argument. Instead just use the
   :class:`~IPython.core.interactiveshell.InteractiveShellEmbed` class.
 
 * ``__IPYTHON__`` is no longer injected into ``__builtin__``.
 
 * :meth:`Struct.__init__` no longer takes `None` as its first argument.  It
   must be a :class:`dict` or :class:`Struct`.
 
 * :meth:`~IPython.core.interactiveshell.InteractiveShell.ipmagic` has been
   renamed :meth:`~IPython.core.interactiveshell.InteractiveShell.magic.`
 
 * The functions :func:`ipmagic` and :func:`ipalias` have been removed from
   :mod:`__builtins__`.
 
 * The references to the global
   :class:`~IPython.core.interactivehell.InteractiveShell` instance (``_ip``, and
   ``__IP``) have been removed from the user's namespace. They are replaced by a
   new function called :func:`get_ipython` that returns the current
   :class:`~IPython.core.interactiveshell.InteractiveShell` instance. This
   function is injected into the user's namespace and is now the main way of
   accessing the running IPython.
 
 * Old style configuration files :file:`ipythonrc` and :file:`ipy_user_conf.py`
   are no longer supported. Users should migrate there configuration files to
   the new format described :ref:`here <config_overview>` and :ref:`here
   <configuring_ipython>`.
 
 * The old IPython extension API that relied on :func:`ipapi` has been
   completely removed. The new extension API is described :ref:`here
   <configuring_ipython>`.
 
 * Support for ``qt3`` has been dropped.  Users who need this should use
   previous versions of IPython.
 
 * Removed :mod:`shellglobals` as it was obsolete.
 
 * Removed all the threaded shells in :mod:`IPython.core.shell`. These are no
   longer needed because of the new capabilities in
   :mod:`IPython.lib.inputhook`.
 
 * New top-level sub-packages have been created: :mod:`IPython.core`, 
   :mod:`IPython.lib`, :mod:`IPython.utils`, :mod:`IPython.deathrow`,
   :mod:`IPython.quarantine`.  All existing top-level modules have been
   moved to appropriate sub-packages.  All internal import statements
   have been updated and tests have been added.  The build system (setup.py
   and friends) have been updated.  See :ref:`this section <module_reorg>` of the
   documentation for descriptions of these new sub-packages.
 
 * :mod:`IPython.ipapi` has been moved to :mod:`IPython.core.ipapi`.
   :mod:`IPython.Shell` and :mod:`IPython.iplib` have been split and removed as
   part of the refactor.
 
 * :mod:`Extensions` has been moved to :mod:`extensions` and all existing
   extensions have been moved to either :mod:`IPython.quarantine` or
   :mod:`IPython.deathrow`. :mod:`IPython.quarantine` contains modules that we
   plan on keeping but that need to be updated. :mod:`IPython.deathrow` contains
   modules that are either dead or that should be maintained as third party
   libraries. More details about this can be found :ref:`here <module_reorg>`.
 
 * Previous IPython GUIs in :mod:`IPython.frontend` and :mod:`IPython.gui` are
   likely broken, and have been removed to :mod:`IPython.deathrow` because of the
   refactoring in the core. With proper updates, these should still work.
 
 
 Known Regressions
 -----------------
 
 We do our best to improve IPython, but there are some known regressions in 0.11
 relative to 0.10.2.  First of all, there are features that have yet to be
 ported to the new APIs, and in order to ensure that all of the installed code
 runs for our users, we have moved them to two separate directories in the
 source distribution, `quarantine` and `deathrow`.  Finally, we have some other
 miscellaneous regressions that we hope to fix as soon as possible.  We now
 describe all of these in more detail.
 
 Quarantine
 ~~~~~~~~~~
 
 These are tools and extensions that we consider relatively easy to update to
 the new classes and APIs, but that we simply haven't had time for.  Any user
 who is interested in one of these is encouraged to help us by porting it and
 submitting a pull request on our `development site`_.
 
 .. _development site: http://github.com/ipython/ipython
 
 Currently, the quarantine directory contains::
 
     clearcmd.py            ipy_fsops.py            ipy_signals.py
     envpersist.py          ipy_gnuglobal.py        ipy_synchronize_with.py
     ext_rescapture.py      ipy_greedycompleter.py  ipy_system_conf.py
     InterpreterExec.py     ipy_jot.py              ipy_which.py
     ipy_app_completers.py  ipy_lookfor.py          ipy_winpdb.py
     ipy_autoreload.py      ipy_profile_doctest.py  ipy_workdir.py
     ipy_completers.py      ipy_pydb.py             jobctrl.py
     ipy_editors.py         ipy_rehashdir.py        ledit.py
     ipy_exportdb.py        ipy_render.py           pspersistence.py
     ipy_extutil.py         ipy_server.py           win32clip.py
 
 Deathrow
 ~~~~~~~~
 
 These packages may be harder to update or make most sense as third-party
 libraries.  Some of them are completely obsolete and have been already replaced
 by better functionality (we simply haven't had the time to carefully weed them
 out so they are kept here for now). Others simply require fixes to code that
 the current core team may not be familiar with.  If a tool you were used to is
 included here, we encourage you to contact the dev list and we can discuss
 whether it makes sense to keep it in IPython (if it can be maintained).
 
 Currently, the deathrow directory contains::
 
     astyle.py              ipy_defaults.py          ipy_vimserver.py
     dtutils.py             ipy_kitcfg.py            numeric_formats.py
     Gnuplot2.py            ipy_legacy.py            numutils.py
     GnuplotInteractive.py  ipy_p4.py                outputtrap.py
     GnuplotRuntime.py      ipy_profile_none.py      PhysicalQInput.py
     ibrowse.py             ipy_profile_numpy.py     PhysicalQInteractive.py
     igrid.py               ipy_profile_scipy.py     quitter.py*
     ipipe.py               ipy_profile_sh.py        scitedirector.py
     iplib.py               ipy_profile_zope.py      Shell.py
     ipy_constants.py       ipy_traits_completer.py  twshell.py
 
 
 Other regressions
 ~~~~~~~~~~~~~~~~~
 
 * The machinery that adds functionality to the 'sh' profile for using IPython
   as your system shell has not been updated to use the new APIs.  As a result,
   only the aesthetic (prompt) changes are still implemented. We intend to fix
   this by 0.12.  Tracked as issue 547_.
 
 .. _547: https://github.com/ipython/ipython/issues/547
 
 * The installation of scripts on Windows was broken without setuptools, so we
   now depend on setuptools on Windows.  We hope to fix setuptools-less
   installation, and then remove the setuptools dependency.  Issue 539_.
 
 .. _539: https://github.com/ipython/ipython/issues/539
 
 * The directory history `_dh` is not saved between sessions.  Issue 634_.
 
 .. _634: https://github.com/ipython/ipython/issues/634
 
 
 Removed Features
 ----------------
 
 As part of the updating of IPython, we have removed a few features for the
 purposes of cleaning up the codebase and interfaces.  These removals are
 permanent, but for any item listed below, equivalent functionality is
 available.
 
 * The magics Exit and Quit have been dropped as ways to exit IPython. Instead,
   the lowercase forms of both work either as a bare name (``exit``) or a
   function call (``exit()``).  You can assign these to other names using
   exec_lines in the config file.
 
 
-.. _credits_011::
+.. _credits_011:
 
 Credits
 -------
 
 Many users and developers contributed code, features, bug reports and ideas to
 this release.  Please do not hesitate in contacting us if we've failed to
 acknowledge your contribution here.  In particular, for this release we have
 contribution from the following people, a mix of new and regular names (in
 alphabetical order by first name):
 
 * Aenugu Sai Kiran Reddy <saikrn08-at-gmail.com>
 * andy wilson <wilson.andrew.j+github-at-gmail.com>
 * Antonio Cuni <antocuni>
 * Barry Wark <barrywark-at-gmail.com>
 * Beetoju Anuradha <anu.beethoju-at-gmail.com>
 * Benjamin Ragan-Kelley <minrk-at-Mercury.local>
 * Brad Reisfeld
 * Brian E. Granger <ellisonbg-at-gmail.com>
 * Christoph Gohlke <cgohlke-at-uci.edu>
 * Cody Precord
 * dan.milstein
 * Darren Dale <dsdale24-at-gmail.com>
 * Dav Clark <davclark-at-berkeley.edu>
 * David Warde-Farley <wardefar-at-iro.umontreal.ca>
 * epatters <ejpatters-at-gmail.com>
 * epatters <epatters-at-caltech.edu>
 * epatters <epatters-at-enthought.com>
 * Eric Firing <efiring-at-hawaii.edu>
 * Erik Tollerud <erik.tollerud-at-gmail.com>
 * Evan Patterson <epatters-at-enthought.com>
 * Fernando Perez <Fernando.Perez-at-berkeley.edu>
 * Gael Varoquaux <gael.varoquaux-at-normalesup.org>
 * Gerardo <muzgash-at-Muzpelheim>
 * Jason Grout <jason.grout-at-drake.edu>
 * John Hunter <jdh2358-at-gmail.com>
 * Jens Hedegaard Nielsen <jenshnielsen-at-gmail.com>
 * Johann Cohen-Tanugi <johann.cohentanugi-at-gmail.com>
 * Jörgen Stenarson <jorgen.stenarson-at-bostream.nu>
 * Justin Riley <justin.t.riley-at-gmail.com>
 * Kiorky
 * Laurent Dufrechou <laurent.dufrechou-at-gmail.com>
 * Luis Pedro Coelho <lpc-at-cmu.edu>
 * Mani chandra <mchandra-at-iitk.ac.in>
 * Mark E. Smith
 * Mark Voorhies <mark.voorhies-at-ucsf.edu>
 * Martin Spacek <git-at-mspacek.mm.st>
 * Michael Droettboom <mdroe-at-stsci.edu>
 * MinRK <benjaminrk-at-gmail.com>
 * muzuiget <muzuiget-at-gmail.com>
 * Nick Tarleton <nick-at-quixey.com>
 * Nicolas Rougier <Nicolas.rougier-at-inria.fr>
 * Omar Andres Zapata Mesa <andresete.chaos-at-gmail.com>
 * Paul Ivanov <pivanov314-at-gmail.com>
 * Pauli Virtanen <pauli.virtanen-at-iki.fi>
 * Prabhu Ramachandran
 * Ramana <sramana9-at-gmail.com>
 * Robert Kern <robert.kern-at-gmail.com>
 * Sathesh Chandra <satheshchandra88-at-gmail.com>
 * Satrajit Ghosh <satra-at-mit.edu>
 * Sebastian Busch
 * Skipper Seabold <jsseabold-at-gmail.com>
 * Stefan van der Walt <bzr-at-mentat.za.net>
 * Stephan Peijnik <debian-at-sp.or.at>
 * Steven Bethard
 * Thomas Kluyver <takowl-at-gmail.com>
 * Thomas Spura <tomspur-at-fedoraproject.org>
 * Tom Fetherston <tfetherston-at-aol.com>
 * Tom MacWright
 * tzanko
 * vankayala sowjanya <hai.sowjanya-at-gmail.com>
 * Vivian De Smedt <vds2212-at-VIVIAN>
 * Ville M. Vainio <vivainio-at-gmail.com>
 * Vishal Vatsa <vishal.vatsa-at-gmail.com>
 * Vishnu S G <sgvishnu777-at-gmail.com>
 * Walter Doerwald <walter-at-livinglogic.de>
 
 .. note::
 
     This list was generated with the output of
     ``git log dev-0.11 HEAD --format='* %aN <%aE>' | sed 's/@/\-at\-/' | sed 's/<>//' | sort -u``
     after some cleanup.  If you should be on this list, please add yourself.

docs/source/whatsnew/version0.12.txt

@@ -1,370 +1,370 b''
 =============
  0.12 Series
 =============
 
 Release 0.12.1
 ==============
 
 IPython 0.12.1 is a bugfix release of 0.12, pulling only bugfixes and minor
 cleanup from 0.13, timed for the Ubuntu 12.04 LTS release.
 
 See the :ref:`list of fixed issues <issues_list_012>` for specific backported issues.
 
 
 Release 0.12
 ============
 
 IPython 0.12 contains several major new features, as well as a large amount of
 bug and regression fixes.  The 0.11 release brought with it a lot of new
 functionality and major refactorings of the codebase; by and large this has
 proven to be a success as the number of contributions to the project has
 increased dramatically, proving that the code is now much more approachable.
 But in the refactoring inevitably some bugs were introduced, and we have also
 squashed many of those as well as recovered some functionality that had been
 temporarily disabled due to the API changes.
 
 The following major new features appear in this version.
 
 
 An interactive browser-based Notebook with rich media support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A powerful new interface puts IPython in your browser. You can start it with
 the command ``ipython notebook``:
 
 .. figure:: ../_static/notebook_specgram.png
     :width: 400px
     :alt: The IPython notebook with embedded text, code, math and figures.
     :align: center
     :target: ../_static/notebook_specgram.png
 
     The new IPython notebook showing text, mathematical expressions in LaTeX,
     code, results and embedded figures created with Matplotlib.
 
 This new interface maintains all the features of IPython you are used to, as it
 is a new client that communicates with the same IPython kernels used by the
 terminal and Qt console.  But the web notebook provides for a different
 workflow where you can integrate, along with code execution, also text,
 mathematical expressions, graphics, video, and virtually any content that a
 modern browser is capable of displaying.
 
 You can save your work sessions as documents that retain all these elements and
 which can be version controlled, emailed to colleagues or saved as HTML or PDF
 files for printing or publishing statically on the web.  The internal storage
 format is a JSON file that can be easily manipulated for manual exporting to
 other formats.
 
 This Notebook is a major milestone for IPython, as for years we have tried to
 build this kind of system.  We were inspired originally by the excellent
 implementation in Mathematica, we made a number of attempts using older
 technologies in earlier Summer of Code projects in 2005 (both students and
 Robert Kern developed early prototypes), and in recent years we have seen the
 excellent implementation offered by the `Sage <http://sagemath.org>` system.
 But we continued to work on something that would be consistent with the rest of
 IPython's design, and it is clear now that the effort was worth it: based on
 the ZeroMQ communications architecture introduced in version 0.11, the notebook
 can now retain 100% of the features of the real IPython.  But it can also
 provide the rich media support and high quality Javascript libraries that were
 not available in browsers even one or two years ago (such as high-quality
 mathematical rendering or built-in video).
 
 The notebook has too many useful and important features to describe in these
 release notes; our documentation now contains a directory called
 ``examples/notebooks`` with several notebooks that illustrate various aspects
 of the system.  You should start by reading those named
 ``00_notebook_tour.ipynb`` and ``01_notebook_introduction.ipynb`` first, and
 then can proceed to read the others in any order you want.
 
 To start the notebook server, go to a directory containing the notebooks you
 want to open (or where you want to create new ones) and type::
 
   ipython notebook
 
 You can see all the relevant options with::
 
   ipython notebook --help
   ipython notebook --help-all  # even more
 
 and just like the Qt console, you can start the notebook server with pylab
 support by using::
   
   ipython notebook --pylab
 
 for floating matplotlib windows or::
   
   ipython notebook --pylab inline
 
 for plotting support with automatically inlined figures.  Note that it is now
 possible also to activate pylab support at runtime via ``%pylab``, so you do
 not need to make this decision when starting the server.
   
 See :ref:`the Notebook docs <htmlnotebook>` for technical details.
 
 .. _two_process_console:
 
 Two-process terminal console
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Based on the same architecture as the notebook and the Qt console, we also have
 now a terminal-based console that can connect to an external IPython kernel
 (the same kernels used by the Qt console or the notebook, in fact).  While this
 client behaves almost identically to the usual IPython terminal application,
 this capability can be very useful to attach an interactive console to an
 existing kernel that was started externally.  It lets you use the interactive
 ``%debug`` facilities in a notebook, for example (the web browser can't
 interact directly with the debugger) or debug a third-party code where you may
 have embedded an IPython kernel.
 
 This is also something that we have wanted for a long time, and which is a
 culmination (as a team effort) of the work started last year during the 2010
 Google Summer of Code project.
   
 Tabbed QtConsole
 ~~~~~~~~~~~~~~~~
 
 The QtConsole now supports starting multiple kernels in tabs, and has a
 menubar, so it looks and behaves more like a real application.  Keyboard
 enthusiasts can disable the menubar with ctrl-shift-M (:ghpull:`887`).
 
 .. figure:: ../_static/qtconsole_tabbed.png
     :width: 400px
     :alt: Tabbed IPython Qt console with embedded plots and menus.
     :align: center
     :target: ../_static/qtconsole_tabbed.png
 
     The improved Qt console for IPython, now with tabs to control multiple
     kernels and full menu support.
 
 
 Full Python 3 compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 IPython can now be installed from a single codebase on Python 2 and
 Python 3. The installation process for Python 3 automatically runs 2to3. The
 same 'default' profile is now used for Python 2 and 3 (the previous version had
 a separate 'python3' profile).
 
 Standalone Kernel
 ~~~~~~~~~~~~~~~~~
 
 The ``ipython kernel`` subcommand has been added, to allow starting a
 standalone kernel, that can be used with various frontends.  You can then later
 connect a Qt console or a terminal console to this kernel by typing e.g.::
 
   ipython qtconsole --existing
 
 if it's the only one running, or by passing explicitly the connection
 parameters (printed by the kernel at startup).
 
 
 PyPy support
 ~~~~~~~~~~~~
 
 The terminal interface to IPython now runs under `PyPy <http://pypy.org/>`_.
 We will continue to monitor PyPy's progress, and hopefully before long at least
 we'll be able to also run the notebook.  The Qt console may take longer, as Qt
 is a very complex set of bindings to a huge C++ library, and that is currently
 the area where PyPy still lags most behind.  But for everyday interactive use
 at the terminal, with this release and PyPy 1.7, things seem to work quite well
 from our admittedly limited testing.
 
   
 Other important new features
 ----------------------------
 
 * **SSH Tunnels**: In 0.11, the :mod:`IPython.parallel` Client could tunnel its
   connections to the Controller via ssh. Now, the QtConsole :ref:`supports
   <ssh_tunnels>` ssh tunneling, as do parallel engines.
 
 * **relaxed command-line parsing**: 0.11 was released with overly-strict
   command-line parsing, preventing the ability to specify arguments with spaces,
   e.g. ``ipython --pylab qt`` or ``ipython -c "print 'hi'"``. This has
   been fixed, by using argparse. The new parsing is a strict superset of 0.11, so
   any commands in 0.11 should still work in 0.12.
 
 * **HistoryAccessor**: The :class:`~IPython.core.history.HistoryManager` class
   for interacting with your IPython SQLite history database has been split,
   adding a parent :class:`~IPython.core.history.HistoryAccessor` class, so that
   users can write code to access and search their IPython history without being
   in an IPython session (:ghpull:`824`).
 
 * **kernel %gui and %pylab**: The ``%gui`` and ``%pylab`` magics have been
   restored to the IPython kernel (e.g. in the qtconsole or notebook). This
   allows activation of pylab-mode, or eventloop integration after starting the
   kernel, which was unavailable in 0.11.  Unlike in the terminal, this can be
   set only once, and cannot be changed.
 
 * **%config**: A new ``%config`` magic has been added, giving easy access to the
   IPython configuration system at runtime (:ghpull:`923`).
 
 * **Multiline History**: Multiline readline history has been restored to the
   Terminal frontend by default (:ghpull:`838`).
 
 * **%store**: The ``%store`` magic from earlier versions has been updated and
   re-enabled (:ref:`extensions_storemagic`; :ghpull:`1029`). To autorestore
   stored variables on startup, specify ``c.StoreMagic.autorestore = True`` in
   :file:`ipython_config.py`.
 
 
 Major Bugs fixed
 ----------------
 
 In this cycle, we have :ref:`closed over 500 issues <issues_list_012>`, but a
 few major ones merit special mention:
 
 * Simple configuration errors should no longer crash IPython. In 0.11, errors
   in config files, as well as invalid trait values, could crash IPython. Now,
   such errors are reported, and help is displayed.
 
 * Certain SyntaxErrors no longer crash IPython (e.g. just typing keywords, such
   as ``return``, ``break``, etc.). See :ghissue:`704`.
 
 * IPython path utils, such as :func:`~IPython.utils.path.get_ipython_dir` now
   check for write permissions, so IPython should function on systems where the
   default path resolution might point to a read-only location, such as
   ``HOMESHARE`` on Windows (:ghissue:`669`).
 
 * :func:`raw_input` now works in the kernel when multiple frontends are in
   use. The request will be sent to the frontend that made the request, and an
   exception is raised if that frontend does not support stdin requests
   (e.g. the notebook) (:ghissue:`673`).
 
 * :mod:`zmq` version detection no longer uses simple lexicographical comparison
   to check minimum version, which prevents 0.11 from working with pyzmq-2.1.10
   (:ghpull:`758`).
 
 * A bug in PySide < 1.0.7 caused crashes on OSX when tooltips were shown
   (:ghissue:`711`). these tooltips are now disabled on old PySide
   (:ghpull:`963`).
 
 * IPython no longer crashes when started on recent versions of Python 3 in
   Windows (:ghissue:`737`).
 
 * Instances of classes defined interactively can now be pickled (:ghissue:`29`;
-:ghpull:`648`). Note that pickling saves a reference to the class definition,
-so unpickling the instances will only work where the class has been defined.
+  :ghpull:`648`). Note that pickling saves a reference to the class definition,
+  so unpickling the instances will only work where the class has been defined.
 
 
 Backwards incompatible changes
 ------------------------------
 
 * IPython connection information is no longer specified via ip/port directly,
   rather via json connection files.  These files are stored in the security
   directory, and enable us to turn on HMAC message authentication by default,
   significantly improving the security of kernels.  Various utility functions
   have been added to :mod:`IPython.lib.kernel`, for easier connecting to existing
   kernels.
 
 * :class:`~IPython.zmq.kernelmanager.KernelManager` now has one ip, and several
   port traits, rather than several ip/port pair ``_addr`` traits. This better
   matches the rest of the code, where the ip cannot not be set separately for
   each channel.
 
 * Custom prompts are now configured using a new class,
-:class:`~IPython.core.prompts.PromptManager`, which has traits for
-:attr:`in_template`, :attr:`in2_template` (the ``...:`` continuation prompt),
-:attr:`out_template` and :attr:`rewrite_template`. This uses Python's string
-formatting system, so you can use ``{time}`` and ``{cwd}``, although we have
-preserved the abbreviations from previous versions, e.g. ``\#`` (prompt number)
-and ``\w`` (working directory). For the list of available fields, refer to the
-source of :file:`IPython/core/prompts.py`.
+  :class:`~IPython.core.prompts.PromptManager`, which has traits for
+  :attr:`in_template`, :attr:`in2_template` (the ``...:`` continuation prompt),
+  :attr:`out_template` and :attr:`rewrite_template`. This uses Python's string
+  formatting system, so you can use ``{time}`` and ``{cwd}``, although we have
+  preserved the abbreviations from previous versions, e.g. ``\#`` (prompt number)
+  and ``\w`` (working directory). For the list of available fields, refer to the
+  source of :file:`IPython/core/prompts.py`.
 
 * The class inheritance of the Launchers in
   :mod:`IPython.parallel.apps.launcher` used by ipcluster has changed, so that
   trait names are more consistent across batch systems. This may require a few
   renames in your config files, if you customized the command-line args for
   launching controllers and engines. The configurable names have also been
   changed to be clearer that they point to class names, and can now be
   specified by name only, rather than requiring the full import path of each
   class, e.g.::
 
     IPClusterEngines.engine_launcher = 'IPython.parallel.apps.launcher.MPIExecEngineSetLauncher'
     IPClusterStart.controller_launcher = 'IPython.parallel.apps.launcher.SSHControllerLauncher'
 
   would now be specified as::
 
     IPClusterEngines.engine_launcher_class = 'MPI'
     IPClusterStart.controller_launcher_class = 'SSH'
 
   The full path will still work, and is necessary for using custom launchers
   not in IPython's launcher module.
   
   Further, MPIExec launcher names are now prefixed with just MPI, to better match
   other batch launchers, and be generally more intuitive.  The MPIExec names are
   deprecated, but continue to work.
 
 * For embedding a shell, note that the parameters ``user_global_ns`` and
   ``global_ns`` have been deprectated in favour of ``user_module`` and
   ``module`` respsectively.  The new parameters expect a module-like object,
   rather than a namespace dict.  The old parameters remain for backwards
   compatibility, although ``user_global_ns`` is now ignored. The ``user_ns``
   parameter works the same way as before, and calling
   :func:`~IPython.frontend.terminal.embed.embed` with no arguments still works
   as before.
 
 
 Development summary and credits
 -------------------------------
 
 The previous version (IPython 0.11) was released on July 31 2011, so this
 release cycle was roughly 4 1/2 months long, we closed a total of 515 issues,
 257 pull requests and 258 regular issues (a :ref:`detailed list
-<issues_list_012>`_ is available).
+<issues_list_012>` is available).
 
 Many users and developers contributed code, features, bug reports and ideas to
 this release.  Please do not hesitate in contacting us if we've failed to
 acknowledge your contribution here.  In particular, for this release we have
 had commits from the following 45 contributors, a mix of new and regular names
 (in alphabetical order by first name):
 
 * Alcides <alcides-at-do-not-span-me.com>
 * Ben Edwards <bedwards-at-cs.unm.edu>
 * Benjamin Ragan-Kelley <benjaminrk-at-gmail.com>
 * Benjamin Thyreau <benjamin.thyreau-at-gmail.com>
 * Bernardo B. Marques <bernardo.fire-at-gmail.com>
 * Bernard Paulus <bprecyclebin-at-gmail.com>
 * Bradley M. Froehle <brad.froehle-at-gmail.com>
 * Brian E. Granger <ellisonbg-at-gmail.com>
 * Christian Boos <cboos-at-bct-technology.com>
 * Daniel Velkov <danielv-at-mylife.com>
 * Erik Tollerud <erik.tollerud-at-gmail.com>
 * Evan Patterson <epatters-at-enthought.com>
 * Felix Werner <Felix.Werner-at-kit.edu>
 * Fernando Perez <Fernando.Perez-at-berkeley.edu>
 * Gabriel <g2p.code-at-gmail.com>
 * Grahame Bowland <grahame-at-angrygoats.net>
 * Hannes Schulz <schulz-at-ais.uni-bonn.de>
 * Jens Hedegaard Nielsen <jenshnielsen-at-gmail.com>
 * Jonathan March <jmarch-at-enthought.com>
 * Jörgen Stenarson <jorgen.stenarson-at-bostream.nu>
 * Julian Taylor <jtaylor.debian-at-googlemail.com>
 * Kefu Chai <tchaikov-at-gmail.com>
 * macgyver <neil.rabinowitz-at-merton.ox.ac.uk>
 * Matt Cottingham <matt.cottingham-at-gmail.com>
 * Matthew Brett <matthew.brett-at-gmail.com>
 * Matthias BUSSONNIER <bussonniermatthias-at-gmail.com>
 * Michael Droettboom <mdboom-at-gmail.com>
 * Nicolas Rougier <Nicolas.Rougier-at-inria.fr>
 * Olivier Verdier <olivier.verdier-at-gmail.com>
 * Omar Andres Zapata Mesa <andresete.chaos-at-gmail.com>
 * Pablo Winant <pablo.winant-at-gmail.com>
 * Paul Ivanov <pivanov314-at-gmail.com>
 * Pauli Virtanen <pav-at-iki.fi>
 * Pete Aykroyd <aykroyd-at-gmail.com>
 * Prabhu Ramachandran <prabhu-at-enthought.com>
 * Puneeth Chaganti <punchagan-at-gmail.com>
 * Robert Kern <robert.kern-at-gmail.com>
 * Satrajit Ghosh <satra-at-mit.edu>
 * Stefan van der Walt <stefan-at-sun.ac.za>
 * Szabolcs Horvát <szhorvat-at-gmail.com>
 * Thomas Kluyver <takowl-at-gmail.com>
 * Thomas Spura <thomas.spura-at-gmail.com>
 * Timo Paulssen <timonator-at-perpetuum-immobile.de>
 * Valentin Haenel <valentin.haenel-at-gmx.de>
 * Yaroslav Halchenko <debian-at-onerussian.com>
    
 .. note::
 
     This list was generated with the output of
     ``git log rel-0.11..HEAD --format='* %aN <%aE>' | sed 's/@/\-at\-/' | sed 's/<>//' | sort -u``
     after some cleanup.  If you should be on this list, please add yourself.

docs/sphinxext/apigen.py

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