Ported the IPython Sphinx directive to 0.11.

This was originally written by John Hunter for the 0.10 API, now it works
with 0.11.  We still need to automate its test suite, but at least now it
runs and the script itself can be executed as a test that produces screen
output and figures in a subdir.

docs/sphinxext/ipython_directive.py

@@ -0,0 +1,641 b''
+# -*- coding: utf-8 -*-
+"""Sphinx directive to support embedded IPython code.
+
+This directive allows pasting of entire interactive IPython sessions, prompts
+and all, and their code will actually get re-executed at doc build time, with
+all prompts renumbered sequentially.
+
+To enable this directive, simply list it in your Sphinx ``conf.py`` file
+(making sure the directory where you placed it is visible to sphinx, as is
+needed for all Sphinx directives).
+
+By default this directive assumes that your prompts are unchanged IPython ones,
+but this can be customized.  For example, the following code in your Sphinx
+config file will configure this directive for the following input/output
+prompts ``Yade [1]:`` and ``-> [1]:``::
+
+ import ipython_directive as id
+ id.rgxin =re.compile(r'(?:In |Yade )\[(\d+)\]:\s?(.*)\s*')
+ id.rgxout=re.compile(r'(?:Out| ->  )\[(\d+)\]:\s?(.*)\s*')
+ id.fmtin ='Yade [%d]:'
+ id.fmtout=' ->  [%d]:'
+
+ from IPython import Config
+ id.CONFIG = Config(
+   prompt_in1="Yade [\#]:",
+   prompt_in2="     .\D..",
+   prompt_out=" ->  [\#]:"
+ )
+ id.reconfig_shell()
+
+ import ipython_console_highlighting as ich
+ ich.IPythonConsoleLexer.input_prompt=
+    re.compile("(Yade \[[0-9]+\]: )|(   \.\.\.+:)")
+ ich.IPythonConsoleLexer.output_prompt=
+    re.compile("(( ->  )|(Out)\[[0-9]+\]: )|(   \.\.\.+:)")
+ ich.IPythonConsoleLexer.continue_prompt=re.compile("   \.\.\.+:")
+
+
+ToDo
+----
+
+- Turn the ad-hoc test() function into a real test suite.
+- Break up ipython-specific functionality from matplotlib stuff into better
+  separated code.
+- Make sure %bookmarks used internally are removed on exit.
+
+
+Authors
+-------
+
+- John D Hunter: orignal author.
+- Fernando Perez: refactoring, documentation, cleanups, port to 0.11.
+- VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations.
+"""
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib
+import cStringIO
+import imp
+import os
+import re
+import shutil
+import sys
+import warnings
+
+# To keep compatibility with various python versions
+try:
+    from hashlib import md5
+except ImportError:
+    from md5 import md5
+
+# Third-party
+import matplotlib
+import sphinx
+from docutils.parsers.rst import directives
+
+matplotlib.use('Agg')
+
+# Our own
+from IPython import Config, IPythonApp
+from IPython.utils.genutils import Term, Tee
+
+#-----------------------------------------------------------------------------
+# Globals
+#-----------------------------------------------------------------------------
+
+sphinx_version = sphinx.__version__.split(".")
+# The split is necessary for sphinx beta versions where the string is
+# '6b1'
+sphinx_version = tuple([int(re.split('[a-z]', x)[0])
+                        for x in sphinx_version[:2]])
+
+COMMENT, INPUT, OUTPUT =  range(3)
+CONFIG = Config()
+rgxin = re.compile('In \[(\d+)\]:\s?(.*)\s*')
+rgxout = re.compile('Out\[(\d+)\]:\s?(.*)\s*')
+fmtin = 'In [%d]:'
+fmtout = 'Out[%d]:'
+
+#-----------------------------------------------------------------------------
+# Functions and class declarations
+#-----------------------------------------------------------------------------
+def block_parser(part):
+    """
+    part is a string of ipython text, comprised of at most one
+    input, one ouput, comments, and blank lines.  The block parser
+    parses the text into a list of::
+
+      blocks = [ (TOKEN0, data0), (TOKEN1, data1), ...]
+
+    where TOKEN is one of [COMMENT | INPUT | OUTPUT ] and
+    data is, depending on the type of token::
+
+      COMMENT : the comment string
+
+      INPUT: the (DECORATOR, INPUT_LINE, REST) where
+         DECORATOR: the input decorator (or None)
+         INPUT_LINE: the input as string (possibly multi-line)
+         REST : any stdout generated by the input line (not OUTPUT)
+
+
+      OUTPUT: the output string, possibly multi-line
+    """
+
+    block = []
+    lines = part.split('\n')
+    N = len(lines)
+    i = 0
+    decorator = None
+    while 1:
+
+        if i==N:
+            # nothing left to parse -- the last line
+            break
+
+        line = lines[i]
+        i += 1
+        line_stripped = line.strip()
+        if line_stripped.startswith('#'):
+            block.append((COMMENT, line))
+            continue
+
+        if line_stripped.startswith('@'):
+            # we're assuming at most one decorator -- may need to
+            # rethink
+            decorator = line_stripped
+            continue
+
+        # does this look like an input line?
+        matchin = rgxin.match(line)
+        if matchin:
+            lineno, inputline = int(matchin.group(1)), matchin.group(2)
+
+            # the ....: continuation string
+            continuation = '   %s:'%''.join(['.']*(len(str(lineno))+2))
+            Nc = len(continuation)
+            # input lines can continue on for more than one line, if
+            # we have a '\' line continuation char or a function call
+            # echo line 'print'.  The input line can only be
+            # terminated by the end of the block or an output line, so
+            # we parse out the rest of the input line if it is
+            # multiline as well as any echo text
+
+            rest = []
+            while i<N:
+
+                # look ahead; if the next line is blank, or a comment, or
+                # an output line, we're done
+
+                nextline = lines[i]
+                matchout = rgxout.match(nextline)
+                #print "nextline=%s, continuation=%s, starts=%s"%(nextline, continuation, nextline.startswith(continuation))
+                if matchout or nextline.startswith('#'):
+                    break
+                elif nextline.startswith(continuation):
+                    inputline += '\n' + nextline[Nc:]
+                else:
+                    rest.append(nextline)
+                i+= 1
+
+            block.append((INPUT, (decorator, inputline, '\n'.join(rest))))
+            continue
+
+        # if it looks like an output line grab all the text to the end
+        # of the block
+        matchout = rgxout.match(line)
+        if matchout:
+            lineno, output = int(matchout.group(1)), matchout.group(2)
+            if i<N-1:
+                output = '\n'.join([output] + lines[i:])
+
+            block.append((OUTPUT, output))
+            break
+
+    return block
+
+
+class EmbeddedSphinxShell(object):
+    """An embedded IPython instance to run inside Sphinx"""
+
+    def __init__(self):
+
+        self.cout = cStringIO.StringIO()
+        Term.cout = self.cout
+        Term.cerr = self.cout
+
+        # For debugging, so we can see normal output, use this:
+        #Term.cout = genutils.Tee(self.cout, channel='stdout') # dbg
+        #Term.cerr = genutils.Tee(self.cout, channel='stderr') # dbg
+
+        # Create config object for IPython
+        config = Config()
+        config.Global.display_banner = False
+        config.Global.exec_lines = ['import numpy as np',
+                                    'from pylab import *'
+                                    ]
+        config.InteractiveShell.autocall = False
+        config.InteractiveShell.autoindent = False
+        config.InteractiveShell.colors = 'NoColor'
+
+        # Merge global config which can be used to override.
+        config._merge(CONFIG)
+
+        # Create and initialize ipython, but don't start its mainloop
+        IP = IPythonApp(override_config=config)
+        IP.initialize()
+
+        # Store a few parts of IPython we'll need.
+        self.IP = IP.shell
+        self.user_ns = self.IP.user_ns
+        self.user_global_ns = self.IP.user_global_ns
+                                    
+        self.input = ''
+        self.output = ''
+
+        self.is_verbatim = False
+        self.is_doctest = False
+        self.is_suppress = False
+
+        # on the first call to the savefig decorator, we'll import
+        # pyplot as plt so we can make a call to the plt.gcf().savefig
+        self._pyplot_imported = False
+
+        # we need bookmark the current dir first so we can save
+        # relative to it
+        self.process_input_line('bookmark ipy_basedir')
+        self.cout.seek(0)
+        self.cout.truncate(0)
+
+    def process_input_line(self, line):
+        """process the input, capturing stdout"""
+        #print "input='%s'"%self.input
+        stdout = sys.stdout
+        try:
+            sys.stdout = self.cout
+            self.IP.push_line(line)
+        finally:
+            sys.stdout = stdout
+
+    # Callbacks for each type of token
+    def process_input(self, data, input_prompt, lineno):
+        """Process data block for INPUT token."""
+        decorator, input, rest = data
+        image_file = None
+        #print 'INPUT:', data  # dbg
+        is_verbatim = decorator=='@verbatim' or self.is_verbatim
+        is_doctest = decorator=='@doctest' or self.is_doctest
+        is_suppress = decorator=='@suppress' or self.is_suppress
+        is_savefig = decorator is not None and \
+                     decorator.startswith('@savefig')
+
+        input_lines = input.split('\n')
+
+        continuation = '   %s:'%''.join(['.']*(len(str(lineno))+2))
+        Nc = len(continuation)
+
+        if is_savefig:
+            saveargs = decorator.split(' ')
+            filename = saveargs[1]
+            outfile = os.path.join('_static/%s'%filename)
+            # build out an image directive like
+            # .. image:: somefile.png
+            #    :width 4in
+            #
+            # from an input like
+            # savefig somefile.png width=4in
+            imagerows = ['.. image:: %s'%outfile]
+
+            for kwarg in saveargs[2:]:
+                arg, val = kwarg.split('=')
+                arg = arg.strip()
+                val = val.strip()
+                imagerows.append('   :%s: %s'%(arg, val))
+
+            image_file = outfile
+            image_directive = '\n'.join(imagerows)
+
+        # TODO: can we get "rest" from ipython
+        #self.process_input_line('\n'.join(input_lines))
+
+        ret = []
+        is_semicolon = False
+
+        for i, line in enumerate(input_lines):
+            if line.endswith(';'):
+                is_semicolon = True
+
+            if i==0:
+                # process the first input line
+                if is_verbatim:
+                    self.process_input_line('')
+                else:
+                    # only submit the line in non-verbatim mode
+                    self.process_input_line(line)
+                formatted_line = '%s %s'%(input_prompt, line)
+            else:
+                # process a continuation line
+                if not is_verbatim:
+                    self.process_input_line(line)
+
+                formatted_line = '%s %s'%(continuation, line)
+
+            if not is_suppress:
+                ret.append(formatted_line)
+
+        if not is_suppress:
+            if len(rest.strip()):
+                if is_verbatim:
+                    # the "rest" is the standard output of the
+                    # input, which needs to be added in
+                    # verbatim mode
+                    ret.append(rest)
+
+        self.cout.seek(0)
+        output = self.cout.read()
+        if not is_suppress and not is_semicolon:
+            ret.append(output)
+
+        self.cout.truncate(0)
+        return ret, input_lines, output, is_doctest, image_file
+        #print 'OUTPUT', output  # dbg
+
+    def process_output(self, data, output_prompt,
+                       input_lines, output, is_doctest, image_file):
+        """Process data block for OUTPUT token."""
+        if is_doctest:
+            submitted = data.strip()
+            found = output
+            if found is not None:
+                found = found.strip()
+                
+                # XXX - fperez: in 0.11, 'output' never comes with the prompt
+                # in it, just the actual output text.  So I think all this code
+                # can be nuked...
+                ## ind = found.find(output_prompt)
+                ## if ind<0:
+                ##     e='output prompt="%s" does not match out line=%s' % \
+                ##        (output_prompt, found)
+                ##     raise RuntimeError(e)
+                ## found = found[len(output_prompt):].strip()
+
+                if found!=submitted:
+                    e = ('doctest failure for input_lines="%s" with '
+                         'found_output="%s" and submitted output="%s"' %
+                         (input_lines, found, submitted) )
+                    raise RuntimeError(e)
+                #print 'doctest PASSED for input_lines="%s" with found_output="%s" and submitted output="%s"'%(input_lines, found, submitted)
+
+    def process_comment(self, data):
+        """Process data block for COMMENT token."""
+        if not self.is_suppress:
+            return [data]
+
+    def process_block(self, block):
+        """
+        process block from the block_parser and return a list of processed lines
+        """
+
+        ret = []
+        output = None
+        input_lines = None
+
+        m = rgxin.match(str(self.IP.outputcache.prompt1).strip())
+        lineno = int(m.group(1))
+
+        input_prompt = fmtin%lineno
+        output_prompt = fmtout%lineno
+        image_file = None
+        image_directive = None
+        # XXX - This needs a second refactor.  There's too much state being
+        # held globally, which makes for a very awkward interface and large,
+        # hard to test functions.  I've already broken this up at least into
+        # three separate processors to isolate the logic better, but this only
+        # serves to highlight the coupling.  Next we need to clean it up...
+        for token, data in block:
+            if token==COMMENT:
+                out_data = self.process_comment(data)
+            elif token==INPUT:
+                out_data, input_lines, output, is_doctest, image_file= \
+                          self.process_input(data, input_prompt, lineno)
+            elif token==OUTPUT:
+                out_data = \
+                    self.process_output(data, output_prompt,
+                                        input_lines, output, is_doctest,
+                                        image_file)
+            if out_data:
+                ret.extend(out_data)
+
+        if image_file is not None:
+            self.ensure_pyplot()
+            command = 'plt.gcf().savefig("%s")'%image_file
+            print 'SAVEFIG', command  # dbg
+            self.process_input_line('bookmark ipy_thisdir')
+            self.process_input_line('cd -b ipy_basedir')
+            self.process_input_line(command)
+            self.process_input_line('cd -b ipy_thisdir')
+            self.cout.seek(0)
+            self.cout.truncate(0)
+        return ret, image_directive
+
+    def ensure_pyplot(self):
+        if self._pyplot_imported:
+            return
+        self.process_input_line('import matplotlib.pyplot as plt')
+
+# A global instance used below. XXX: not sure why this can't be created inside
+# ipython_directive itself.
+shell = EmbeddedSphinxShell()
+
+def reconfig_shell():
+    """Called after setting module-level variables to re-instantiate
+    with the set values (since shell is instantiated first at import-time
+    when module variables have default values)"""
+    global shell
+    shell = EmbeddedSphinxShell()
+
+
+def ipython_directive(name, arguments, options, content, lineno,
+                      content_offset, block_text, state, state_machine,
+                      ):
+
+    debug = ipython_directive.DEBUG
+    shell.is_suppress = options.has_key('suppress')
+    shell.is_doctest = options.has_key('doctest')
+    shell.is_verbatim = options.has_key('verbatim')
+
+    #print 'ipy', shell.is_suppress, options
+    parts = '\n'.join(content).split('\n\n')
+    lines = ['.. sourcecode:: ipython', '']
+
+    figures = []
+    for part in parts:
+        block = block_parser(part)
+
+        if len(block):
+            rows, figure = shell.process_block(block)
+            for row in rows:
+                lines.extend(['    %s'%line for line in row.split('\n')])
+
+            if figure is not None:
+                figures.append(figure)
+
+    for figure in figures:
+        lines.append('')
+        lines.extend(figure.split('\n'))
+        lines.append('')
+
+    #print lines
+    if len(lines)>2:
+        if debug:
+            print '\n'.join(lines)
+        else:
+            #print 'INSERTING %d lines'%len(lines)
+            state_machine.insert_input(
+                lines, state_machine.input_lines.source(0))
+
+    return []
+
+ipython_directive.DEBUG = False
+ipython_directive.DEBUG = True  # dbg
+
+# Enable as a proper Sphinx directive
+def setup(app):
+    setup.app = app
+    options = {'suppress': directives.flag,
+               'doctest': directives.flag,
+               'verbatim': directives.flag,
+               }
+
+    app.add_directive('ipython', ipython_directive, True, (0, 2, 0), **options)
+
+
+# Simple smoke test, needs to be converted to a proper automatic test.
+def test():
+
+    examples = [
+        r"""
+In [9]: pwd
+Out[9]: '/home/jdhunter/py4science/book'
+
+In [10]: cd bookdata/
+/home/jdhunter/py4science/book/bookdata
+
+In [2]: from pylab import *
+
+In [2]: ion()
+
+In [3]: im = imread('stinkbug.png')
+
+@savefig mystinkbug.png width=4in
+In [4]: imshow(im)
+Out[4]: <matplotlib.image.AxesImage object at 0x39ea850>
+        
+""",
+        r"""
+
+In [1]: x = 'hello world'
+
+# string methods can be
+# used to alter the string
+@doctest
+In [2]: x.upper()
+Out[2]: 'HELLO WORLD'
+
+@verbatim
+In [3]: x.st<TAB>
+x.startswith  x.strip
+""",
+    r"""
+
+In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\
+   .....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv'
+
+In [131]: print url.split('&')
+['http://ichart.finance.yahoo.com/table.csv?s=CROX', 'd=9', 'e=22', 'f=2009', 'g=d', 'a=1', 'b=8', 'c=2006', 'ignore=.csv']
+
+In [60]: import urllib
+
+""",
+    r"""\
+
+In [133]: import numpy.random
+
+@suppress
+In [134]: numpy.random.seed(2358)
+
+@doctest
+In [135]: np.random.rand(10,2)
+Out[135]:
+array([[ 0.64524308,  0.59943846],
+       [ 0.47102322,  0.8715456 ],
+       [ 0.29370834,  0.74776844],
+       [ 0.99539577,  0.1313423 ],
+       [ 0.16250302,  0.21103583],
+       [ 0.81626524,  0.1312433 ],
+       [ 0.67338089,  0.72302393],
+       [ 0.7566368 ,  0.07033696],
+       [ 0.22591016,  0.77731835],
+       [ 0.0072729 ,  0.34273127]])
+
+""",
+
+    r"""
+In [106]: print x
+jdh
+
+In [109]: for i in range(10):
+   .....:     print i
+   .....:
+   .....:
+0
+1
+2
+3
+4
+5
+6
+7
+8
+9
+""",
+
+        r"""
+
+In [144]: from pylab import *
+
+In [145]: ion()
+
+# use a semicolon to suppress the output
+@savefig test_hist.png width=4in
+In [151]: hist(np.random.randn(10000), 100);
+
+
+@savefig test_plot.png width=4in
+In [151]: plot(np.random.randn(10000), 'o');
+   """,
+
+        r"""
+# use a semicolon to suppress the output
+In [151]: plt.clf()
+
+@savefig plot_simple.png width=4in
+In [151]: plot([1,2,3])
+
+@savefig hist_simple.png width=4in
+In [151]: hist(np.random.randn(10000), 100);
+
+""",
+     r"""
+# update the current fig
+In [151]: ylabel('number')
+
+In [152]: title('normal distribution')
+
+
+@savefig hist_with_text.png
+In [153]: grid(True)
+
+        """,
+        ]
+
+    #ipython_directive.DEBUG = True  # dbg
+    #options = dict(suppress=True)  # dbg
+    options = dict()
+    for example in examples:
+        content = example.split('\n')
+        ipython_directive('debug', arguments=None, options=options,
+                          content=content, lineno=0,
+                          content_offset=None, block_text=None,
+                          state=None, state_machine=None,
+                          )
+
+# Run test suite as a script
+if __name__=='__main__':
+    if not os.path.isdir('_static'):
+        os.mkdir('_static')
+    test()
+    print 'All OK? Check figures in _static/'

IPython/__init__.py

@@ -1,63 +1,67 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 IPython.
 
 IPython is a set of tools for interactive and exploratory computing in Python.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+from __future__ import absolute_import
 
 import os
 import sys
-from IPython.core import release
 
 #-----------------------------------------------------------------------------
 # Setup everything
 #-----------------------------------------------------------------------------
 
 if sys.version[0:3] < '2.5':
     raise ImportError('Python Version 2.5 or above is required for IPython.')
 
 
 # Make it easy to import extensions - they are always directly on pythonpath.
 # Therefore, non-IPython modules can be added to extensions directory
 sys.path.append(os.path.join(os.path.dirname(__file__), "extensions"))
 
 #-----------------------------------------------------------------------------
 # Setup the top level names
 #-----------------------------------------------------------------------------
 
 # In some cases, these are causing circular imports.
-from IPython.core.iplib import InteractiveShell
-from IPython.core.embed import embed
-from IPython.core.error import TryNext
-from IPython.testing import test
+from .config.loader import Config
+from .core import release
+from .core.application import Application
+from .core.ipapp import IPythonApp
+from .core.embed import embed
+from .core.error import TryNext
+from .core.iplib import InteractiveShell
+from .testing import test
 
-from IPython.lib import (
+from .lib import (
     enable_wx, disable_wx,
     enable_gtk, disable_gtk,
     enable_qt4, disable_qt4,
     enable_tk, disable_tk,
     set_inputhook, clear_inputhook,
     current_gui, spin,
     appstart_qt4, appstart_wx,
     appstart_gtk, appstart_tk
 )
 
 # Release data
 __author__ = ''
 for author, email in release.authors.values():
     __author__ += author + ' <' + email + '>\n'
 __license__  = release.license
 __version__  = release.version
 __revision__ = release.revision

IPython/core/application.py

@@ -1,417 +1,490 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 An application for IPython.
 
 All top-level applications should use the classes in this module for
 handling configuration and creating componenets.
 
 The job of an :class:`Application` is to create the master configuration 
 object and then create the components, passing the config to them.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  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 logging
 import os
 import sys
 
 from IPython.core import release, crashhandler
 from IPython.utils.genutils import get_ipython_dir, get_ipython_package_dir
 from IPython.config.loader import (
     PyFileConfigLoader,
     ArgParseConfigLoader,
     Config,
 )
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class ApplicationError(Exception):
     pass
 
 
 app_cl_args = (
     (('--ipython-dir', ), dict(
         dest='Global.ipython_dir',type=unicode,
         help=
         """Set to override default location of the IPython directory
         IPYTHON_DIR, stored as Global.ipython_dir.  This can also be specified
         through the environment variable IPYTHON_DIR.""",
         metavar='Global.ipython_dir') ),
     (('-p', '--profile',), dict(
         dest='Global.profile',type=unicode,
         help=
         """The string name of the ipython profile to be used.  Assume that your
         config file is ipython_config-<name>.py (looks in current dir first,
         then in IPYTHON_DIR). This is a quick way to keep and load multiple
         config files for different tasks, especially if include your basic one
         in your more specialized ones.  You can keep a basic
         IPYTHON_DIR/ipython_config.py file and then have other 'profiles' which
         include this one and load extra things for particular tasks.""",
         metavar='Global.profile') ),
     (('--log-level',), dict(
         dest="Global.log_level",type=int,
         help='Set the log level (0,10,20,30,40,50).  Default is 30.',
         metavar='Global.log_level')),
     (('--config-file',), dict(
         dest='Global.config_file',type=unicode,
         help=
         """Set the config file name to override default.  Normally IPython
         loads ipython_config.py (from current directory) or
         IPYTHON_DIR/ipython_config.py.  If the loading of your config file
         fails, IPython starts with a bare bones configuration (no modules
         loaded at all).""",
         metavar='Global.config_file')),
     )
 
 class Application(object):
-    """Load a config, construct components and set them running."""
+    """Load a config, construct components and set them running.
+
+    The configuration of an application can be done via four different Config
+    objects, which are loaded and ultimately merged into a single one used from
+    that point on by the app.  These are:
+
+    1. default_config: internal defaults, implemented in code.
+    2. file_config: read from the filesystem.
+    3. command_line_config: read from the system's command line flags.
+    4. constructor_config: passed parametrically to the constructor.
+
+    During initialization, 3 is actually read before 2, since at the
+    command-line one may override the location of the file to be read.  But the
+    above is the order in which the merge is made.
+
+    There is a final config object can be created and passed to the
+    constructor: override_config.  If it exists, this completely overrides the
+    configs 2-4 above (the default is still used to ensure that all needed
+    fields at least are created).  This makes it easier to create
+    parametrically (e.g. in testing or sphinx plugins) objects with a known
+    configuration, that are unaffected by whatever arguments may be present in
+    sys.argv or files in the user's various directories.
+    """
 
     name = u'ipython'
     description = 'IPython: an enhanced interactive Python shell.'
     #: usage message printed by argparse. If None, auto-generate
     usage = None
     config_file_name = u'ipython_config.py'
-    # Track the default and actual separately because some messages are
-    # only printed if we aren't using the default.
+    #: Track the default and actual separately because some messages are
+    #: only printed if we aren't using the default.
     default_config_file_name = config_file_name
     default_log_level = logging.WARN
-    # Set by --profile option
+    #: Set by --profile option
     profile_name = None
     #: User's ipython directory, typically ~/.ipython/
     ipython_dir = None
+    #: internal defaults, implemented in code.
+    default_config = None
+    #: read from the filesystem
+    file_config = None
+    #: read from the system's command line flags
+    command_line_config = None
+    #: passed parametrically to the constructor.
+    constructor_config = None
+    #: final override, if given supercedes file/command/constructor configs
+    override_config = None
     #: A reference to the argv to be used (typically ends up being sys.argv[1:])
     argv = None
     #: Default command line arguments.  Subclasses should create a new tuple
     #: that *includes* these.
     cl_arguments = app_cl_args
 
+    #: extra arguments computed by the command-line loader
+    extra_args = None
+
     # Private attributes
     _exiting = False
     _initialized = False
 
     # Class choices for things that will be instantiated at runtime.
     _CrashHandler = crashhandler.CrashHandler
 
-    def __init__(self, argv=None):
+    def __init__(self, argv=None, constructor_config=None, override_config=None):
         self.argv = sys.argv[1:] if argv is None else argv
+        self.constructor_config = constructor_config
+        self.override_config = override_config
         self.init_logger()
 
     def init_logger(self):
         self.log = logging.getLogger(self.__class__.__name__)
         # This is used as the default until the command line arguments are read.
         self.log.setLevel(self.default_log_level)
         self._log_handler = logging.StreamHandler()
         self._log_formatter = logging.Formatter("[%(name)s] %(message)s")
         self._log_handler.setFormatter(self._log_formatter)
         self.log.addHandler(self._log_handler)
 
     def _set_log_level(self, level):
         self.log.setLevel(level)
 
     def _get_log_level(self):
         return self.log.level
 
     log_level = property(_get_log_level, _set_log_level)
 
     def initialize(self):
-        """Start the application."""
+        """Initialize the application.
+
+        Loads all configuration information and sets all application state, but
+        does not start any relevant processing (typically some kind of event
+        loop).
+
+        Once this method has been called, the application is flagged as
+        initialized and the method becomes a no-op."""
         
         if self._initialized:
             return
 
         # The first part is protected with an 'attempt' wrapper, that will log
         # failures with the basic system traceback machinery.  Once our crash
         # handler is in place, we can let any subsequent exception propagate,
         # as our handler will log it with much better detail than the default.
         self.attempt(self.create_crash_handler)
+
+        # Configuration phase
+        # Default config (internally hardwired in application code)
         self.create_default_config()
         self.log_default_config()
         self.set_default_config_log_level()
-        self.pre_load_command_line_config()
-        self.load_command_line_config()
-        self.set_command_line_config_log_level()
-        self.post_load_command_line_config()
-        self.log_command_line_config()
+
+        if self.override_config is None:
+            # Command-line config
+            self.pre_load_command_line_config()
+            self.load_command_line_config()
+            self.set_command_line_config_log_level()
+            self.post_load_command_line_config()
+            self.log_command_line_config()
+
+        # Find resources needed for filesystem access, using information from
+        # the above two
         self.find_ipython_dir()
         self.find_resources()
         self.find_config_file_name()
         self.find_config_file_paths()
-        self.pre_load_file_config()
-        self.load_file_config()
-        self.set_file_config_log_level()
-        self.post_load_file_config()
-        self.log_file_config()
+
+        if self.override_config is None:
+            # File-based config
+            self.pre_load_file_config()
+            self.load_file_config()
+            self.set_file_config_log_level()
+            self.post_load_file_config()
+            self.log_file_config()
+
+        # Merge all config objects into a single one the app can then use
         self.merge_configs()
         self.log_master_config()
+
+        # Construction phase
         self.pre_construct()
         self.construct()
         self.post_construct()
+
+        # Done, flag as such and
         self._initialized = True
 
     def start(self):
+        """Start the application."""
         self.initialize()
         self.start_app()
 
     #-------------------------------------------------------------------------
     # Various stages of Application creation
     #-------------------------------------------------------------------------
 
     def create_crash_handler(self):
         """Create a crash handler, typically setting sys.excepthook to it."""
         self.crash_handler = self._CrashHandler(self, self.name)
         sys.excepthook = self.crash_handler
 
     def create_default_config(self):
         """Create defaults that can't be set elsewhere.
 
         For the most part, we try to set default in the class attributes
         of Components.  But, defaults the top-level Application (which is
         not a HasTraitlets or Component) are not set in this way.  Instead
         we set them here.  The Global section is for variables like this that
         don't belong to a particular component.
         """
         c = Config()
         c.Global.ipython_dir = get_ipython_dir()
         c.Global.log_level = self.log_level
         self.default_config = c
 
     def log_default_config(self):
         self.log.debug('Default config loaded:')
         self.log.debug(repr(self.default_config))
 
     def set_default_config_log_level(self):
         try:
             self.log_level = self.default_config.Global.log_level
         except AttributeError:
             # Fallback to the default_log_level class attribute
             pass
 
     def create_command_line_config(self):
         """Create and return a command line config loader."""
         return ArgParseConfigLoader(self.argv, self.cl_arguments,
                                     description=self.description, 
                                     version=release.version,
                                     usage=self.usage,
                                     )
 
     def pre_load_command_line_config(self):
         """Do actions just before loading the command line config."""
         pass
 
     def load_command_line_config(self):
         """Load the command line config."""
         loader = self.create_command_line_config()
         self.command_line_config = loader.load_config()
         self.extra_args = loader.get_extra_args()
 
     def set_command_line_config_log_level(self):
         try:
             self.log_level = self.command_line_config.Global.log_level
         except AttributeError:
             pass
 
     def post_load_command_line_config(self):
         """Do actions just after loading the command line config."""
         pass
 
     def log_command_line_config(self):
         self.log.debug("Command line config loaded:")
         self.log.debug(repr(self.command_line_config))
 
     def find_ipython_dir(self):
         """Set the IPython directory.
 
         This sets ``self.ipython_dir``, but the actual value that is passed to
         the application is kept in either ``self.default_config`` or
         ``self.command_line_config``.  This also adds ``self.ipython_dir`` to
         ``sys.path`` so config files there can be referenced by other config
         files.
         """
 
         try:
             self.ipython_dir = self.command_line_config.Global.ipython_dir
         except AttributeError:
             self.ipython_dir = self.default_config.Global.ipython_dir
         sys.path.append(os.path.abspath(self.ipython_dir))
         if not os.path.isdir(self.ipython_dir):
             os.makedirs(self.ipython_dir, mode=0777)
         self.log.debug("IPYTHON_DIR set to: %s" % self.ipython_dir)
 
     def find_resources(self):
         """Find other resources that need to be in place.
 
         Things like cluster directories need to be in place to find the
         config file.  These happen right after the IPython directory has
         been set.
         """
         pass
 
     def find_config_file_name(self):
         """Find the config file name for this application.
 
         This must set ``self.config_file_name`` to the filename of the
         config file to use (just the filename). The search paths for the
         config file are set in :meth:`find_config_file_paths` and then passed
         to the config file loader where they are resolved to an absolute path.
 
         If a profile has been set at the command line, this will resolve it.
         """
 
         try:
             self.config_file_name = self.command_line_config.Global.config_file
         except AttributeError:
             pass
 
         try:
             self.profile_name = self.command_line_config.Global.profile
         except AttributeError:
             pass
         else:
             name_parts = self.config_file_name.split('.')
             name_parts.insert(1, u'_' + self.profile_name + u'.')
             self.config_file_name = ''.join(name_parts)
 
     def find_config_file_paths(self):
         """Set the search paths for resolving the config file.
 
         This must set ``self.config_file_paths`` to a sequence of search
         paths to pass to the config file loader.
         """
         # Include our own profiles directory last, so that users can still find
         # our shipped copies of builtin profiles even if they don't have them
         # in their local ipython directory.
         prof_dir = os.path.join(get_ipython_package_dir(), 'config', 'profile')
         self.config_file_paths = (os.getcwd(), self.ipython_dir, prof_dir)
 
     def pre_load_file_config(self):
         """Do actions before the config file is loaded."""
         pass
 
     def load_file_config(self):
         """Load the config file.
         
         This tries to load the config file from disk.  If successful, the
         ``CONFIG_FILE`` config variable is set to the resolved config file
         location.  If not successful, an empty config is used.
         """
         self.log.debug("Attempting to load config file: %s" %
                        self.config_file_name)
         loader = PyFileConfigLoader(self.config_file_name,
                                     path=self.config_file_paths)
         try:
             self.file_config = loader.load_config()
             self.file_config.Global.config_file = loader.full_filename
         except IOError:
             # Only warn if the default config file was NOT being used.
             if not self.config_file_name==self.default_config_file_name:
                 self.log.warn("Config file not found, skipping: %s" %
                                self.config_file_name, exc_info=True)
             self.file_config = Config()
         except:
             self.log.warn("Error loading config file: %s" %
                           self.config_file_name, exc_info=True)
             self.file_config = Config()
 
     def set_file_config_log_level(self):
         # We need to keeep self.log_level updated.  But we only use the value
         # of the file_config if a value was not specified at the command
         # line, because the command line overrides everything.
         if not hasattr(self.command_line_config.Global, 'log_level'):
             try:
                 self.log_level = self.file_config.Global.log_level
             except AttributeError:
                 pass # Use existing value
 
     def post_load_file_config(self):
         """Do actions after the config file is loaded."""
         pass
 
     def log_file_config(self):
         if hasattr(self.file_config.Global, 'config_file'):
             self.log.debug("Config file loaded: %s" %
                            self.file_config.Global.config_file)
             self.log.debug(repr(self.file_config))
 
     def merge_configs(self):
         """Merge the default, command line and file config objects."""
         config = Config()
         config._merge(self.default_config)
-        config._merge(self.file_config)
-        config._merge(self.command_line_config)
+        if self.override_config is None:
+            config._merge(self.file_config)
+            config._merge(self.command_line_config)
+            if self.constructor_config is not None:
+                config._merge(self.constructor_config)
+        else:
+            config._merge(self.override_config)
+        # XXX fperez - propose to Brian we rename master_config to simply
+        # config, I think this is going to be heavily used in examples and
+        # application code and the name is shorter/easier to find/remember.
+        # For now, just alias it...
         self.master_config = config
+        self.config = config
 
     def log_master_config(self):
         self.log.debug("Master config created:")
         self.log.debug(repr(self.master_config))
 
     def pre_construct(self):
         """Do actions after the config has been built, but before construct."""
         pass
 
     def construct(self):
         """Construct the main components that make up this app."""
         self.log.debug("Constructing components for application")
 
     def post_construct(self):
         """Do actions after construct, but before starting the app."""
         pass
 
     def start_app(self):
         """Actually start the app."""
         self.log.debug("Starting application")
 
     #-------------------------------------------------------------------------
     # Utility methods
     #-------------------------------------------------------------------------
 
     def abort(self):
         """Abort the starting of the application."""
         if self._exiting:
             pass
         else:
             self.log.critical("Aborting application: %s" % self.name, exc_info=True)
             self._exiting = True
             sys.exit(1)
 
     def exit(self, exit_status=0):
         if self._exiting:
             pass
         else:
             self.log.debug("Exiting application: %s" % self.name)
             self._exiting = True
             sys.exit(exit_status)
 
     def attempt(self, func, action='abort'):
         try:
             func()
         except SystemExit:
             raise
         except:
             if action == 'abort':
                 self.log.critical("Aborting application: %s" % self.name,
                                   exc_info=True)
                 self.abort()
                 raise
             elif action == 'exit':
                 self.exit(0)
 

IPython/core/ipapp.py

@@ -1,643 +1,655 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The :class:`~IPython.core.application.Application` object for the command
 line :command:`ipython` program.
 
 Authors
 -------
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import absolute_import
 
 import logging
 import os
 import sys
 
 from IPython.core import crashhandler
 from IPython.core.application import Application
 from IPython.core.iplib import InteractiveShell
 from IPython.config.loader import (
     Config,
     PyFileConfigLoader,
 #    NoConfigDefault,
 )
 from IPython.lib import inputhook
 from IPython.utils.genutils import filefind, get_ipython_dir
 from . import usage
 
 #-----------------------------------------------------------------------------
 # Globals, utilities and helpers
 #-----------------------------------------------------------------------------
 
 default_config_file_name = u'ipython_config.py'
 
 cl_args = (
     (('--autocall',), dict(
         type=int, dest='InteractiveShell.autocall',
         help=
         """Make IPython automatically call any callable object even if you
         didn't type explicit parentheses. For example, 'str 43' becomes
         'str(43)' automatically.  The value can be '0' to disable the feature,
         '1' for 'smart' autocall, where it is not applied if there are no more
         arguments on the line, and '2' for 'full' autocall, where all callable
         objects are automatically called (even if no arguments are present).
         The default is '1'.""",
         metavar='InteractiveShell.autocall')
     ),
     (('--autoindent',), dict(
         action='store_true', dest='InteractiveShell.autoindent',
         help='Turn on autoindenting.')
     ),
     (('--no-autoindent',), dict(
         action='store_false', dest='InteractiveShell.autoindent',
         help='Turn off autoindenting.')
     ),
     (('--automagic',), dict(
         action='store_true', dest='InteractiveShell.automagic',
         help='Turn on the auto calling of magic commands.'
         'Type %%magic at  the  IPython  prompt  for  more information.')
      ),
     (('--no-automagic',), dict(
         action='store_false', dest='InteractiveShell.automagic',
         help='Turn off the auto calling of magic commands.')
     ),
     (('--autoedit-syntax',), dict(
         action='store_true', dest='InteractiveShell.autoedit_syntax',
         help='Turn on auto editing of files with syntax errors.')
     ),
     (('--no-autoedit-syntax',), dict(
         action='store_false', dest='InteractiveShell.autoedit_syntax',
         help='Turn off auto editing of files with syntax errors.')
     ),
     (('--banner',), dict(
         action='store_true', dest='Global.display_banner',
         help='Display a banner upon starting IPython.')
     ),
     (('--no-banner',), dict(
         action='store_false', dest='Global.display_banner',
         help="Don't display a banner upon starting IPython.")
     ),
     (('--cache-size',), dict(
         type=int, dest='InteractiveShell.cache_size',
         help=
         """Set the size of the output cache.  The default is 1000, you can
         change it permanently in your config file.  Setting it to 0 completely
         disables the caching system, and the minimum value accepted is 20 (if
         you provide a value less than 20, it is reset to 0 and a warning is
         issued).  This limit is defined because otherwise you'll spend more
         time re-flushing a too small cache than working.
         """,
         metavar='InteractiveShell.cache_size')
     ),
     (('--classic',), dict(
         action='store_true', dest='Global.classic',
         help="Gives IPython a similar feel to the classic Python prompt.")
     ),
     (('--colors',), dict(
         type=str, dest='InteractiveShell.colors',
         help="Set the color scheme (NoColor, Linux, and LightBG).",
         metavar='InteractiveShell.colors')
     ),
     (('--color-info',), dict(
         action='store_true', dest='InteractiveShell.color_info',
         help=
         """IPython can display information about objects via a set of func-
         tions, and optionally can use colors for this, syntax highlighting
         source code and various other elements.  However, because this
         information is passed through a pager (like 'less') and many pagers get
         confused with color codes, this option is off by default.  You can test
         it and turn it on permanently in your ipython_config.py file if it
         works for you.  Test it and turn it on permanently if it works with
         your system.  The magic function %%color_info allows you to toggle this
         inter- actively for testing."""
         )
     ),
     (('--no-color-info',), dict(
         action='store_false', dest='InteractiveShell.color_info',
         help="Disable using colors for info related things.")
     ),
     (('--confirm-exit',), dict(
         action='store_true', dest='InteractiveShell.confirm_exit',
         help=
         """Set to confirm when you try to exit IPython with an EOF (Control-D
         in Unix, Control-Z/Enter in Windows). By typing 'exit', 'quit' or
         '%%Exit', you can force a direct exit without any confirmation.
         """
         )
     ),
     (('--no-confirm-exit',), dict(
         action='store_false', dest='InteractiveShell.confirm_exit',
         help="Don't prompt the user when exiting.")
     ),
     (('--deep-reload',), dict(
         action='store_true', dest='InteractiveShell.deep_reload',
         help=
         """Enable deep (recursive) reloading by default. IPython can use the
         deep_reload module which reloads changes in modules recursively (it
         replaces the reload() function, so you don't need to change anything to
         use it). deep_reload() forces a full reload of modules whose code may
         have changed, which the default reload() function does not.  When
         deep_reload is off, IPython will use the normal reload(), but
         deep_reload will still be available as dreload(). This fea- ture is off
         by default [which means that you have both normal reload() and
         dreload()].""")
     ),
     (('--no-deep-reload',), dict(
         action='store_false', dest='InteractiveShell.deep_reload',
         help="Disable deep (recursive) reloading by default.")
     ),
     (('--editor',), dict(
         type=str, dest='InteractiveShell.editor',
         help="Set the editor used by IPython (default to $EDITOR/vi/notepad).",
         metavar='InteractiveShell.editor')
     ),
     (('--log','-l'), dict(
         action='store_true', dest='InteractiveShell.logstart',
         help="Start logging to the default log file (./ipython_log.py).")
     ),
     (('--logfile','-lf'), dict(
         type=unicode, dest='InteractiveShell.logfile',
         help="Start logging to logfile with this name.",
         metavar='InteractiveShell.logfile')
     ),
     (('--log-append','-la'), dict(
         type=unicode, dest='InteractiveShell.logappend',
         help="Start logging to the given file in append mode.",
         metavar='InteractiveShell.logfile')
     ),
     (('--pdb',), dict(
         action='store_true', dest='InteractiveShell.pdb',
         help="Enable auto calling the pdb debugger after every exception.")
     ),
     (('--no-pdb',), dict(
         action='store_false', dest='InteractiveShell.pdb',
         help="Disable auto calling the pdb debugger after every exception.")
     ),
     (('--pprint',), dict(
         action='store_true', dest='InteractiveShell.pprint',
         help="Enable auto pretty printing of results.")
     ),
     (('--no-pprint',), dict(
         action='store_false', dest='InteractiveShell.pprint',
         help="Disable auto auto pretty printing of results.")
     ),
     (('--prompt-in1','-pi1'), dict(
         type=str, dest='InteractiveShell.prompt_in1',
         help=
         """Set the main input prompt ('In [\#]: ').  Note that if you are using
         numbered prompts, the number is represented with a '\#' in the string.
         Don't forget to quote strings with spaces embedded in them. Most
         bash-like escapes can be used to customize IPython's prompts, as well
         as a few additional ones which are IPython-spe- cific.  All valid
         prompt escapes are described in detail in the Customization section of
         the IPython manual.""",
         metavar='InteractiveShell.prompt_in1')
     ),
     (('--prompt-in2','-pi2'), dict(
         type=str, dest='InteractiveShell.prompt_in2',
         help=
         """Set the secondary input prompt (' .\D.: ').  Similar to the previous
         option, but used for the continuation prompts. The special sequence
         '\D' is similar to '\#', but with all digits replaced by dots (so you
         can have your continuation prompt aligned with your input prompt).
         Default: ' .\D.: ' (note three spaces at the start for alignment with
         'In [\#]')""",
         metavar='InteractiveShell.prompt_in2')
     ),
     (('--prompt-out','-po'), dict(
         type=str, dest='InteractiveShell.prompt_out',
         help="Set the output prompt ('Out[\#]:')",
         metavar='InteractiveShell.prompt_out')
     ),
     (('--quick',), dict(
         action='store_true', dest='Global.quick',
         help="Enable quick startup with no config files.")
     ),
     (('--readline',), dict(
         action='store_true', dest='InteractiveShell.readline_use',
         help="Enable readline for command line usage.")
     ),
     (('--no-readline',), dict(
         action='store_false', dest='InteractiveShell.readline_use',
         help="Disable readline for command line usage.")
     ),
     (('--screen-length','-sl'), dict(
         type=int, dest='InteractiveShell.screen_length',
         help=
         """Number of lines of your screen, used to control printing of very
         long strings.  Strings longer than this number of lines will be sent
         through a pager instead of directly printed.  The default value for
         this is 0, which means IPython will auto-detect your screen size every
         time it needs to print certain potentially long strings (this doesn't
         change the behavior of the 'print' keyword, it's only triggered
         internally). If for some reason this isn't working well (it needs
         curses support), specify it yourself. Otherwise don't change the
         default.""",
         metavar='InteractiveShell.screen_length')
     ),
     (('--separate-in','-si'), dict(
         type=str, dest='InteractiveShell.separate_in',
         help="Separator before input prompts.  Default '\\n'.",
         metavar='InteractiveShell.separate_in')
     ),
     (('--separate-out','-so'), dict(
         type=str, dest='InteractiveShell.separate_out',
         help="Separator before output prompts.  Default 0 (nothing).",
         metavar='InteractiveShell.separate_out')
     ),
     (('--separate-out2','-so2'), dict(
         type=str, dest='InteractiveShell.separate_out2',
         help="Separator after output prompts.  Default 0 (nonight).",
         metavar='InteractiveShell.separate_out2')
     ),
     (('-no-sep',), dict(
         action='store_true', dest='Global.nosep',
         help="Eliminate all spacing between prompts.")
     ),
     (('--term-title',), dict(
         action='store_true', dest='InteractiveShell.term_title',
         help="Enable auto setting the terminal title.")
     ),
     (('--no-term-title',), dict(
         action='store_false', dest='InteractiveShell.term_title',
         help="Disable auto setting the terminal title.")
     ),
     (('--xmode',), dict(
         type=str, dest='InteractiveShell.xmode',
         help=
         """Exception reporting mode ('Plain','Context','Verbose').  Plain:
         similar to python's normal traceback printing.  Context: prints 5 lines
         of context source code around each line in the traceback.  Verbose:
         similar to Context, but additionally prints the variables currently
         visible where the exception happened (shortening their strings if too
         long).  This can potentially be very slow, if you happen to have a huge
         data structure whose string representation is complex to compute.
         Your computer may appear to freeze for a while with cpu usage at 100%%.
         If this occurs, you can cancel the traceback with Ctrl-C (maybe hitting
         it more than once).
         """,
         metavar='InteractiveShell.xmode')
     ),
     (('--ext',), dict(
         type=str, dest='Global.extra_extension',
         help="The dotted module name of an IPython extension to load.",
         metavar='Global.extra_extension')
     ),
     (('-c',), dict(
         type=str, dest='Global.code_to_run',
         help="Execute the given command string.",
         metavar='Global.code_to_run')
     ),
     (('-i',), dict(
         action='store_true', dest='Global.force_interact',
         help=
         "If running code from the command line, become interactive afterwards."
         )
     ),
 
     # Options to start with GUI control enabled from the beginning
     (('--gui',), dict(
         type=str, dest='Global.gui',
         help="Enable GUI event loop integration ('qt', 'wx', 'gtk').",
         metavar='gui-mode')
     ),
 
     (('--pylab','-pylab'), dict(
         type=str, dest='Global.pylab',
         nargs='?', const='auto', metavar='gui-mode',
         help="Pre-load matplotlib and numpy for interactive use. "+
         "If no value is given, the gui backend is matplotlib's, else use "+
         "one of:  ['tk', 'qt', 'wx', 'gtk'].")
     ),
     
     # Legacy GUI options.  Leave them in for backwards compatibility, but the
     # 'thread' names are really a misnomer now.
     (('--wthread','-wthread'), dict(
         action='store_true', dest='Global.wthread',
         help="Enable wxPython event loop integration "+
              "(DEPRECATED, use --gui wx)")
     ),
     (('--q4thread','--qthread','-q4thread','-qthread'), dict(
         action='store_true', dest='Global.q4thread',
         help="Enable Qt4 event loop integration. Qt3 is no longer supported. "+
              "(DEPRECATED, use --gui qt)")
     ),
     (('--gthread','-gthread'), dict(
         action='store_true', dest='Global.gthread',
         help="Enable GTK event loop integration. "+
              "(DEPRECATED, use --gui gtk)")
     ),
 )
 
 #-----------------------------------------------------------------------------
 # Main classes and functions
 #-----------------------------------------------------------------------------
 
 class IPythonApp(Application):
     name = u'ipython'
     #: argparse formats better the 'usage' than the 'description' field
     description = None
     #: usage message printed by argparse. If None, auto-generate
     usage = usage.cl_usage
 
     config_file_name = default_config_file_name
 
     cl_arguments = Application.cl_arguments + cl_args
 
     # Private and configuration attributes
     _CrashHandler = crashhandler.IPythonCrashHandler
     
-    def __init__(self, argv=None, **shell_params):
+    def __init__(self, argv=None,
+                 constructor_config=None, override_config=None,
+                 **shell_params):
         """Create a new IPythonApp.
 
+        See the parent class for details on how configuration is handled.
+
         Parameters
         ----------
         argv : optional, list
           If given, used as the command-line argv environment to read arguments
           from.
 
+        constructor_config : optional, Config
+          If given, additional config that is merged last, after internal
+          defaults, command-line and file-based configs.
+
+        override_config : optional, Config
+          If given, config that overrides all others unconditionally (except
+          for internal defaults, which ensure that all parameters exist).
+
         shell_params : optional, dict
           All other keywords are passed to the :class:`iplib.InteractiveShell`
           constructor. 
         """
-        super(IPythonApp, self).__init__(argv)
+        super(IPythonApp, self).__init__(argv, constructor_config,
+                                         override_config)
         self.shell_params = shell_params
 
     def create_default_config(self):
         super(IPythonApp, self).create_default_config()
         # Eliminate multiple lookups
         Global = self.default_config.Global
 
         # Set all default values
         Global.display_banner = True
         
         # If the -c flag is given or a file is given to run at the cmd line
         # like "ipython foo.py", normally we exit without starting the main
         # loop.  The force_interact config variable allows a user to override
         # this and interact.  It is also set by the -i cmd line flag, just
         # like Python.
         Global.force_interact = False
 
         # By default always interact by starting the IPython mainloop.
         Global.interact = True
 
         # No GUI integration by default
         Global.gui = False
         # Pylab off by default
         Global.pylab = False
 
         # Deprecated versions of gui support that used threading, we support
         # them just for bacwards compatibility as an alternate spelling for
         # '--gui X'
         Global.qthread = False
         Global.q4thread = False
         Global.wthread = False
         Global.gthread = False
 
     def load_file_config(self):
         if hasattr(self.command_line_config.Global, 'quick'):
             if self.command_line_config.Global.quick:
                 self.file_config = Config()
                 return
         super(IPythonApp, self).load_file_config()
 
     def post_load_file_config(self):
         if hasattr(self.command_line_config.Global, 'extra_extension'):
             if not hasattr(self.file_config.Global, 'extensions'):
                 self.file_config.Global.extensions = []
             self.file_config.Global.extensions.append(
                 self.command_line_config.Global.extra_extension)
             del self.command_line_config.Global.extra_extension
 
     def pre_construct(self):
         config = self.master_config
 
         if hasattr(config.Global, 'classic'):
             if config.Global.classic:
                 config.InteractiveShell.cache_size = 0
                 config.InteractiveShell.pprint = 0
                 config.InteractiveShell.prompt_in1 = '>>> '
                 config.InteractiveShell.prompt_in2 = '... '
                 config.InteractiveShell.prompt_out = ''
                 config.InteractiveShell.separate_in = \
                     config.InteractiveShell.separate_out = \
                     config.InteractiveShell.separate_out2 = ''
                 config.InteractiveShell.colors = 'NoColor'
                 config.InteractiveShell.xmode = 'Plain'
 
         if hasattr(config.Global, 'nosep'):
             if config.Global.nosep:
                 config.InteractiveShell.separate_in = \
                 config.InteractiveShell.separate_out = \
                 config.InteractiveShell.separate_out2 = ''
 
         # if there is code of files to run from the cmd line, don't interact
         # unless the -i flag (Global.force_interact) is true.
         code_to_run = config.Global.get('code_to_run','')
         file_to_run = False
-        if len(self.extra_args)>=1:
-            if self.extra_args[0]:
+        if self.extra_args and self.extra_args[0]:
                 file_to_run = True
         if file_to_run or code_to_run:
             if not config.Global.force_interact:
                 config.Global.interact = False
 
     def construct(self):
         # I am a little hesitant to put these into InteractiveShell itself.
         # But that might be the place for them
         sys.path.insert(0, '')
 
         # Create an InteractiveShell instance
         self.shell = InteractiveShell(None, self.master_config,
                                       **self.shell_params )
 
     def post_construct(self):
         """Do actions after construct, but before starting the app."""
         config = self.master_config
         
         # shell.display_banner should always be False for the terminal 
         # based app, because we call shell.show_banner() by hand below
         # so the banner shows *before* all extension loading stuff.
         self.shell.display_banner = False
 
         if config.Global.display_banner and \
             config.Global.interact:
             self.shell.show_banner()
 
         # Make sure there is a space below the banner.
         if self.log_level <= logging.INFO: print
 
         # Now a variety of things that happen after the banner is printed.
         self._enable_gui_pylab()
         self._load_extensions()
         self._run_exec_lines()
         self._run_exec_files()
         self._run_cmd_line_code()
         self._configure_xmode()
 
     def _enable_gui_pylab(self):
         """Enable GUI event loop integration, taking pylab into account."""
         Global = self.master_config.Global
 
         # Select which gui to use
         if Global.gui:
             gui = Global.gui
         # The following are deprecated, but there's likely to be a lot of use
         # of this form out there, so we might as well support it for now.  But
         # the --gui option above takes precedence.
         elif Global.wthread:
             gui = inputhook.GUI_WX
         elif Global.qthread:
             gui = inputhook.GUI_QT
         elif Global.gthread:
             gui = inputhook.GUI_GTK
         else:
             gui = None
 
         # Using --pylab will also require gui activation, though which toolkit
         # to use may be chosen automatically based on mpl configuration.
         if Global.pylab:
             activate = self.shell.enable_pylab
             if Global.pylab == 'auto':
                 gui = None
             else:
                 gui = Global.pylab
         else:
             # Enable only GUI integration, no pylab
             activate = inputhook.enable_gui
 
         if gui or Global.pylab:
             try:
                 self.log.info("Enabling GUI event loop integration, "
                               "toolkit=%s, pylab=%s" % (gui, Global.pylab) )
                 activate(gui)
             except:
                 self.log.warn("Error in enabling GUI event loop integration:")
                 self.shell.showtraceback()
 
     def _load_extensions(self):
         """Load all IPython extensions in Global.extensions.
 
         This uses the :meth:`InteractiveShell.load_extensions` to load all
         the extensions listed in ``self.master_config.Global.extensions``.
         """
         try:
             if hasattr(self.master_config.Global, 'extensions'):
                 self.log.debug("Loading IPython extensions...")
                 extensions = self.master_config.Global.extensions
                 for ext in extensions:
                     try:
                         self.log.info("Loading IPython extension: %s" % ext)                        
                         self.shell.load_extension(ext)
                     except:
                         self.log.warn("Error in loading extension: %s" % ext)
                         self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in loading extensions:")
             self.shell.showtraceback()
 
     def _run_exec_lines(self):
         """Run lines of code in Global.exec_lines in the user's namespace."""
         try:
             if hasattr(self.master_config.Global, 'exec_lines'):
                 self.log.debug("Running code from Global.exec_lines...")
                 exec_lines = self.master_config.Global.exec_lines
                 for line in exec_lines:
                     try:
                         self.log.info("Running code in user namespace: %s" % line)
                         self.shell.runlines(line)
                     except:
                         self.log.warn("Error in executing line in user namespace: %s" % line)
                         self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in handling Global.exec_lines:")
             self.shell.showtraceback()
 
     def _exec_file(self, fname):
         full_filename = filefind(fname, [u'.', self.ipython_dir])
         if os.path.isfile(full_filename):
             if full_filename.endswith(u'.py'):
                 self.log.info("Running file in user namespace: %s" % full_filename)
                 self.shell.safe_execfile(full_filename, self.shell.user_ns)
             elif full_filename.endswith('.ipy'):
                 self.log.info("Running file in user namespace: %s" % full_filename)
                 self.shell.safe_execfile_ipy(full_filename)
             else:
                 self.log.warn("File does not have a .py or .ipy extension: <%s>" % full_filename)
 
     def _run_exec_files(self):
         try:
             if hasattr(self.master_config.Global, 'exec_files'):
                 self.log.debug("Running files in Global.exec_files...")
                 exec_files = self.master_config.Global.exec_files
                 for fname in exec_files:
                     self._exec_file(fname)
         except:
             self.log.warn("Unknown error in handling Global.exec_files:")
             self.shell.showtraceback()
 
     def _run_cmd_line_code(self):
         if hasattr(self.master_config.Global, 'code_to_run'):
             line = self.master_config.Global.code_to_run
             try:
                 self.log.info("Running code given at command line (-c): %s" % line)
                 self.shell.runlines(line)
             except:
                 self.log.warn("Error in executing line in user namespace: %s" % line)
                 self.shell.showtraceback()
             return
         # Like Python itself, ignore the second if the first of these is present
         try:
             fname = self.extra_args[0]
         except:
             pass
         else:
             try:
                 self._exec_file(fname)
             except:
                 self.log.warn("Error in executing file in user namespace: %s" % fname)
                 self.shell.showtraceback()
 
     def _configure_xmode(self):
         # XXX - shouldn't this be read from the config?  I'm still a little
         # lost with all the details of handling the new config guys...
         self.shell.InteractiveTB.set_mode(mode=self.shell.xmode)
         
     def start_app(self):
         if self.master_config.Global.interact:
             self.log.debug("Starting IPython's mainloop...")
             self.shell.mainloop()
         else:
             self.log.debug("IPython not interactive, start_app is no-op...")
 
 
 def load_default_config(ipython_dir=None):
     """Load the default config file from the default ipython_dir.
 
     This is useful for embedded shells.
     """
     if ipython_dir is None:
         ipython_dir = get_ipython_dir()
     cl = PyFileConfigLoader(default_config_file_name, ipython_dir)
     config = cl.load_config()
     return config
 
 
 def launch_new_instance():
     """Create and run a full blown IPython instance"""
     app = IPythonApp()
     app.start()