Merge in all development done in bzr since February 16 2008.

At that time, a clean bzr branch was started from the SVN tree, but
without SVN history.  That SVN history has now been used as the basis
of this branch, and the development done on the history-less BZR
branch has been added and is the content of this merge.  

This branch will be the new official main line of development in
Launchpad (equivalent to the old SVN trunk).

.checkeol

@@ -0,0 +1,2 b''
+[LF]
+*.py

IPython/Extensions/ipy_autoreload.py

@@ -0,0 +1,244 b''
+"""
+IPython extension: autoreload modules before executing the next line
+
+Try:: 
+
+    %autoreload?
+
+for documentation.
+"""
+
+# Pauli Virtanen <[e-mail]>, 2008.
+# Thomas Heller, 2000.
+#
+# This IPython module is written by Pauli Virtanen, based on the autoreload
+# code by Thomas Heller.
+
+#------------------------------------------------------------------------------
+# Autoreload functionality
+#------------------------------------------------------------------------------
+
+import time, os, threading, sys, types, imp, inspect, traceback, atexit
+
+def _get_compiled_ext():
+    """Official way to get the extension of compiled files (.pyc or .pyo)"""
+    for ext, mode, typ in imp.get_suffixes():
+        if typ == imp.PY_COMPILED:
+            return ext
+
+PY_COMPILED_EXT = _get_compiled_ext()
+
+class ModuleReloader(object):
+    skipped = {}
+    """Modules that failed to reload: {module: mtime-on-failed-reload, ...}"""
+    
+    modules = {}
+    """Modules specially marked as autoreloadable."""
+
+    skip_modules = {}
+    """Modules specially marked as not autoreloadable."""
+
+    check_all = True
+    """Autoreload all modules, not just those listed in 'modules'"""
+    
+    def check(self, check_all=False):
+        """Check whether some modules need to be reloaded."""
+        
+        if check_all or self.check_all:
+            modules = sys.modules.keys()
+        else:
+            modules = self.modules.keys()
+        
+        for modname in modules:
+            m = sys.modules.get(modname, None)
+
+            if modname in self.skip_modules:
+                continue
+            
+            if not hasattr(m, '__file__'):
+                continue
+            
+            if m.__name__ == '__main__':
+                # we cannot reload(__main__)
+                continue
+            
+            filename = m.__file__
+            dirname = os.path.dirname(filename)
+            path, ext = os.path.splitext(filename)
+            
+            if ext.lower() == '.py':
+                ext = PY_COMPILED_EXT
+                filename = os.path.join(dirname, path + PY_COMPILED_EXT)
+            
+            if ext != PY_COMPILED_EXT:
+                continue
+            
+            try:
+                pymtime = os.stat(filename[:-1]).st_mtime
+                if pymtime <= os.stat(filename).st_mtime:
+                    continue
+                if self.skipped.get(filename[:-1], None) == pymtime:
+                    continue
+            except OSError:
+                continue
+            
+            try:
+                superreload(m)
+                if filename[:-1] in self.skipped:
+                    del self.skipped[filename[:-1]]
+            except:
+                self.skipped[filename[:-1]] = pymtime
+
+def update_function(old, new, attrnames):
+    for name in attrnames:
+        setattr(old, name, getattr(new, name))
+
+def superreload(module, reload=reload):
+    """Enhanced version of the builtin reload function.
+    
+    superreload replaces the class dictionary of every top-level
+    class in the module with the new one automatically,
+    as well as every function's code object.
+    
+    """
+
+    module = reload(module)
+    
+    # iterate over all objects and update them
+    count = 0
+    for name, new_obj in module.__dict__.items():
+        key = (module.__name__, name)
+        if _old_objects.has_key(key):
+            for old_obj in _old_objects[key]:
+                if type(new_obj) == types.ClassType:
+                    old_obj.__dict__.update(new_obj.__dict__)
+                    count += 1
+                elif type(new_obj) == types.FunctionType:
+                    update_function(old_obj,
+                           new_obj,
+                           "func_code func_defaults func_doc".split())
+                    count += 1
+                elif type(new_obj) == types.MethodType:
+                    update_function(old_obj.im_func,
+                           new_obj.im_func,
+                           "func_code func_defaults func_doc".split())
+                    count += 1
+    
+    return module
+
+reloader = ModuleReloader()
+
+#------------------------------------------------------------------------------
+# IPython monkey-patching
+#------------------------------------------------------------------------------
+
+import IPython.iplib
+
+autoreload_enabled = False
+
+def runcode_hook(self):
+    if not autoreload_enabled:
+        raise IPython.ipapi.TryNext
+    try:
+        reloader.check()
+    except:
+        pass
+
+
+def enable_autoreload():
+    global autoreload_enabled
+    autoreload_enabled = True
+    
+
+def disable_autoreload():
+    global autoreload_enabled
+    autoreload_enabled = False
+    
+#------------------------------------------------------------------------------
+# IPython connectivity
+#------------------------------------------------------------------------------
+
+import IPython.ipapi
+ip = IPython.ipapi.get()
+
+def autoreload_f(self, parameter_s=''):
+    r""" %autoreload => Reload modules automatically
+
+    %autoreload
+    Reload all modules (except thoses excluded by %aimport) automatically now.
+
+    %autoreload 1
+    Reload all modules imported with %aimport every time before executing
+    the Python code typed.
+
+    %autoreload 2
+    Reload all modules (except thoses excluded by %aimport) every time
+    before executing the Python code typed.
+
+    Reloading Python modules in a reliable way is in general
+    difficult, and unexpected things may occur. Some of the common
+    caveats relevant for 'autoreload' are:
+
+    - Modules are not reloaded in any specific order, and no dependency
+      analysis is done. For example, modules with 'from xxx import foo'
+      retain old versions of 'foo' when 'xxx' is autoreloaded.
+    - Functions or objects imported from the autoreloaded module to
+      the interactive namespace are not updated.
+    - C extension modules cannot be reloaded, and so cannot be
+      autoreloaded.
+    """
+    if parameter_s == '':
+        reloader.check(True)
+    elif parameter_s == '0':
+        disable_autoreload()
+    elif parameter_s == '1':
+        reloader.check_all = False
+        enable_autoreload()
+    elif parameter_s == '2':
+        reloader.check_all = True
+        enable_autoreload()
+
+def aimport_f(self, parameter_s=''):
+    """%aimport => Import modules for automatic reloading.
+
+    %aimport
+    List modules to automatically import and not to import.
+
+    %aimport foo
+    Import module 'foo' and mark it to be autoreloaded for %autoreload 1
+
+    %aimport -foo
+    Mark module 'foo' to not be autoreloaded for %autoreload 1
+
+    """
+    
+    modname = parameter_s
+    if not modname:
+        to_reload = reloader.modules.keys()
+        to_reload.sort()
+        to_skip = reloader.skip_modules.keys()
+        to_skip.sort()
+        if reloader.check_all:
+            print "Modules to reload:\nall-expect-skipped"
+        else:
+            print "Modules to reload:\n%s" % ' '.join(to_reload)
+        print "\nModules to skip:\n%s" % ' '.join(to_skip)
+    elif modname.startswith('-'):
+        modname = modname[1:]
+        try: del reloader.modules[modname]
+        except KeyError: pass
+        reloader.skip_modules[modname] = True
+    else:
+        try: del reloader.skip_modules[modname]
+        except KeyError: pass
+        reloader.modules[modname] = True
+
+        mod = __import__(modname)
+        ip.to_user_ns({modname: mod})
+
+def init():
+    ip.expose_magic('autoreload', autoreload_f)
+    ip.expose_magic('aimport', aimport_f)
+    ip.set_hook('pre_runcode_hook', runcode_hook)
+    
+init()
  No newline at end of file

IPython/Extensions/ipy_bzr.py

@@ -0,0 +1,343 b''
+""" Extension for bzr command tab completer. Supports comlpeting commands and options
+
+Unlike the core IPython, you should note that this extension is under GPL, not BSD.
+
+Based on "shell" bzr plugin by Aaron Bentley, license is below. The IPython additions
+are at the bottom of the file, the rest is left untouched.
+
+Must be loaded with ip.load('ipy_bzr') 
+
+""" 
+
+# Copyright (C) 2004, 2005 Aaron Bentley
+# <[e-mail]>
+#
+#    This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation; either version 2 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program; if not, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+import cmd
+from itertools import chain
+import os
+import shlex
+import stat
+import string
+import sys
+
+from bzrlib import osutils
+from bzrlib.branch import Branch
+from bzrlib.config import config_dir, ensure_config_dir_exists
+from bzrlib.commands import get_cmd_object, get_all_cmds, get_alias
+from bzrlib.errors import BzrError
+from bzrlib.workingtree import WorkingTree
+import bzrlib.plugin
+
+
+SHELL_BLACKLIST = set(['rm', 'ls'])
+COMPLETION_BLACKLIST = set(['shell'])
+
+
+class BlackListedCommand(BzrError):
+    def __init__(self, command):
+        BzrError.__init__(self, "The command %s is blacklisted for shell use" %
+                          command)
+
+
+class CompletionContext(object):
+    def __init__(self, text, command=None, prev_opt=None, arg_pos=None):
+        self.text = text
+        self.command = command
+        self.prev_opt = prev_opt
+        self.arg_pos = None
+
+    def get_completions(self):
+        try:
+            return self.get_completions_or_raise()
+        except Exception, e:
+            print e, type(e)
+            return []
+
+    def get_option_completions(self):
+        try:
+            command_obj = get_cmd_object(self.command)
+        except BzrError:
+            return []
+        opts = [o+" " for o in iter_opt_completions(command_obj)]
+        return list(filter_completions(opts, self.text))
+
+    def get_completions_or_raise(self):
+        if self.command is None:
+            if '/' in self.text:
+                iter = iter_executables(self.text)
+            else:
+                iter = (c+" " for c in iter_command_names() if
+                        c not in COMPLETION_BLACKLIST)
+            return list(filter_completions(iter, self.text))
+        if self.prev_opt is None:
+            completions = self.get_option_completions()
+            if self.command == "cd":
+                iter = iter_dir_completions(self.text)
+                completions.extend(list(filter_completions(iter, self.text)))
+            else:
+                iter = iter_file_completions(self.text)
+                completions.extend(filter_completions(iter, self.text))
+            return completions
+
+
+class PromptCmd(cmd.Cmd):
+
+    def __init__(self):
+        cmd.Cmd.__init__(self)
+        self.prompt = "bzr> "
+        try:
+            self.tree = WorkingTree.open_containing('.')[0]
+        except:
+            self.tree = None
+        self.set_title()
+        self.set_prompt()
+        self.identchars += '-'
+        ensure_config_dir_exists()
+        self.history_file = osutils.pathjoin(config_dir(), 'shell-history')
+        readline.set_completer_delims(string.whitespace)
+        if os.access(self.history_file, os.R_OK) and \
+            os.path.isfile(self.history_file):
+            readline.read_history_file(self.history_file)
+        self.cwd = os.getcwd()
+
+    def write_history(self):
+        readline.write_history_file(self.history_file)
+
+    def do_quit(self, args):
+        self.write_history()
+        raise StopIteration
+
+    def do_exit(self, args):
+        self.do_quit(args)
+
+    def do_EOF(self, args):
+        print
+        self.do_quit(args)
+
+    def postcmd(self, line, bar):
+        self.set_title()
+        self.set_prompt()
+
+    def set_prompt(self):
+        if self.tree is not None:
+            try:
+                prompt_data = (self.tree.branch.nick, self.tree.branch.revno(),
+                               self.tree.relpath('.'))
+                prompt = " %s:%d/%s" % prompt_data
+            except:
+                prompt = ""
+        else:
+            prompt = ""
+        self.prompt = "bzr%s> " % prompt
+
+    def set_title(self, command=None):
+        try:
+            b = Branch.open_containing('.')[0]
+            version = "%s:%d" % (b.nick, b.revno())
+        except:
+            version = "[no version]"
+        if command is None:
+            command = ""
+        sys.stdout.write(terminal.term_title("bzr %s %s" % (command, version)))
+
+    def do_cd(self, line):
+        if line == "":
+            line = "~"
+        line = os.path.expanduser(line)
+        if os.path.isabs(line):
+            newcwd = line
+        else:
+            newcwd = self.cwd+'/'+line
+        newcwd = os.path.normpath(newcwd)
+        try:
+            os.chdir(newcwd)
+            self.cwd = newcwd
+        except Exception, e:
+            print e
+        try:
+            self.tree = WorkingTree.open_containing(".")[0]
+        except:
+            self.tree = None
+
+    def do_help(self, line):
+        self.default("help "+line)
+
+    def default(self, line):
+        args = shlex.split(line)
+        alias_args = get_alias(args[0])
+        if alias_args is not None:
+            args[0] = alias_args.pop(0)
+
+        commandname = args.pop(0)
+        for char in ('|', '<', '>'):
+            commandname = commandname.split(char)[0]
+        if commandname[-1] in ('|', '<', '>'):
+            commandname = commandname[:-1]
+        try:
+            if commandname in SHELL_BLACKLIST:
+                raise BlackListedCommand(commandname)
+            cmd_obj = get_cmd_object(commandname)
+        except (BlackListedCommand, BzrError):
+            return os.system(line)
+
+        try:
+            if too_complicated(line):
+                return os.system("bzr "+line)
+            else:
+                return (cmd_obj.run_argv_aliases(args, alias_args) or 0)
+        except BzrError, e:
+            print e
+        except KeyboardInterrupt, e:
+            print "Interrupted"
+        except Exception, e:
+#            print "Unhandled error:\n%s" % errors.exception_str(e)
+            print "Unhandled error:\n%s" % (e)
+
+
+    def completenames(self, text, line, begidx, endidx):
+        return CompletionContext(text).get_completions()
+
+    def completedefault(self, text, line, begidx, endidx):
+        """Perform completion for native commands.
+
+        :param text: The text to complete
+        :type text: str
+        :param line: The entire line to complete
+        :type line: str
+        :param begidx: The start of the text in the line
+        :type begidx: int
+        :param endidx: The end of the text in the line
+        :type endidx: int
+        """
+        (cmd, args, foo) = self.parseline(line)
+        if cmd == "bzr":
+            cmd = None
+        return CompletionContext(text, command=cmd).get_completions()
+
+
+def run_shell():
+    try:
+        prompt = PromptCmd()
+        try:
+            prompt.cmdloop()
+        finally:
+            prompt.write_history()
+    except StopIteration:
+        pass
+
+
+def iter_opt_completions(command_obj):
+    for option_name, option in command_obj.options().items():
+        yield "--" + option_name
+        short_name = option.short_name()
+        if short_name:
+            yield "-" + short_name
+
+
+def iter_file_completions(arg, only_dirs = False):
+    """Generate an iterator that iterates through filename completions.
+
+    :param arg: The filename fragment to match
+    :type arg: str
+    :param only_dirs: If true, match only directories
+    :type only_dirs: bool
+    """
+    cwd = os.getcwd()
+    if cwd != "/":
+        extras = [".", ".."]
+    else:
+        extras = []
+    (dir, file) = os.path.split(arg)
+    if dir != "":
+        listingdir = os.path.expanduser(dir)
+    else:
+        listingdir = cwd
+    for file in chain(os.listdir(listingdir), extras):
+        if dir != "":
+            userfile = dir+'/'+file
+        else:
+            userfile = file
+        if userfile.startswith(arg):
+            if os.path.isdir(listingdir+'/'+file):
+                userfile+='/'
+                yield userfile
+            elif not only_dirs:
+                yield userfile + ' '
+
+
+def iter_dir_completions(arg):
+    """Generate an iterator that iterates through directory name completions.
+
+    :param arg: The directory name fragment to match
+    :type arg: str
+    """
+    return iter_file_completions(arg, True)
+
+
+def iter_command_names(hidden=False):
+    for real_cmd_name, cmd_class in get_all_cmds():
+        if not hidden and cmd_class.hidden:
+            continue
+        for name in [real_cmd_name] + cmd_class.aliases:
+            # Don't complete on aliases that are prefixes of the canonical name
+            if name == real_cmd_name or not real_cmd_name.startswith(name):
+                yield name
+
+
+def iter_executables(path):
+    dirname, partial = os.path.split(path)
+    for filename in os.listdir(dirname):
+        if not filename.startswith(partial):
+            continue
+        fullpath = os.path.join(dirname, filename)
+        mode=os.lstat(fullpath)[stat.ST_MODE]
+        if stat.S_ISREG(mode) and 0111 & mode:
+            yield fullpath + ' '
+
+
+def filter_completions(iter, arg):
+    return (c for c in iter if c.startswith(arg))
+
+
+def iter_munged_completions(iter, arg, text):
+    for completion in iter:
+        completion = str(completion)
+        if completion.startswith(arg):
+            yield completion[len(arg)-len(text):]+" "
+
+
+def too_complicated(line):
+    for char in '|<>*?':
+        if char in line:
+            return True
+    return False
+
+    
+### IPython mods start
+
+def init_ipython(ip):
+    def bzr_completer(self,ev):
+        #print "bzr complete"
+        tup =  ev.line.split(None,2)
+        if len(tup) > 2:
+            cmd = tup[1]
+        else:
+            cmd = None
+                  
+        return CompletionContext(ev.symbol, command = cmd).get_completions()
+    bzrlib.plugin.load_plugins()
+    ip.set_hook('complete_command', bzr_completer, str_key = 'bzr')    

IPython/Extensions/ipy_greedycompleter.py

@@ -0,0 +1,75 b''
+""" Greedy completer extension for IPython
+
+Normal tab completer refuses to evaluate nonsafe stuff. This will evaluate
+everything, so you need to consider the consequences of pressing tab 
+yourself!
+
+Note that this extension simplifies readline interaction by setting
+only whitespace as completer delimiter. If this works well, we will
+do the same in default completer.
+
+"""
+from IPython import generics,ipapi
+from IPython.genutils import dir2
+
+def attr_matches(self, text):
+    """Compute matches when text contains a dot.
+
+    MONKEYPATCHED VERSION (ipy_greedycompleter.py)
+    
+    Assuming the text is of the form NAME.NAME....[NAME], and is
+    evaluatable in self.namespace or self.global_namespace, it will be
+    evaluated and its attributes (as revealed by dir()) are used as
+    possible completions.  (For class instances, class members are are
+    also considered.)
+
+    WARNING: this can still invoke arbitrary C code, if an object
+    with a __getattr__ hook is evaluated.
+
+    """
+    import re
+
+    force_complete = 1
+    # Another option, seems to work great. Catches things like ''.<tab>
+    m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
+
+    if m:
+        expr, attr = m.group(1, 3)
+    else:
+        # force match - eval anything that ends with colon
+        if not force_complete:
+            return []
+                
+        m2 = re.match(r"(.+)\.(\w*)$", self.lbuf)
+        if not m2:
+            return []
+        expr, attr = m2.group(1,2)
+        
+            
+    try:        
+        obj = eval(expr, self.namespace)
+    except:
+        try:
+            obj = eval(expr, self.global_namespace)
+        except:
+            return []
+
+    words = dir2(obj)
+    
+    try:
+        words = generics.complete_object(obj, words)
+    except ipapi.TryNext:
+        pass
+    # Build match list to return
+    n = len(attr)
+    res = ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
+    return res
+
+def main():
+    import readline
+    readline.set_completer_delims(" \n\t")
+    # monkeypatch - the code will be folded to normal completer later on
+    import IPython.completer
+    IPython.completer.Completer.attr_matches = attr_matches
+
+main()
  No newline at end of file

IPython/Extensions/ipy_jot.py

@@ -0,0 +1,311 b''
+# -*- coding: utf-8 -*-
+"""
+%jot magic for lightweight persistence.
+
+Stores variables in Struct with some notes in PicleShare database
+
+
+"""
+
+from datetime import datetime 
+import IPython.ipapi
+ip = IPython.ipapi.get()
+
+import pickleshare
+
+import inspect,pickle,os,sys,textwrap
+from IPython.FakeModule import FakeModule
+from IPython.ipstruct import Struct 
+
+
+def refresh_variables(ip, key=None):
+    db = ip.db
+    if key is None:
+        keys = db.keys('jot/*')
+    else:
+        keys = db.keys('jot/'+key)
+    for key in keys:
+        # strip autorestore
+        justkey = os.path.basename(key)
+        print "Restoring from", justkey, "..."
+        try:
+            obj = db[key]
+        except KeyError:
+            print "Unable to restore variable '%s', ignoring (use %%jot -d to forget!)" % justkey
+            print "The error was:",sys.exc_info()[0]
+        else:
+            #print "restored",justkey,"=",obj #dbg
+            try:
+                origname = obj.name
+            except:
+                ip.user_ns[justkey] = obj
+                print "Restored", justkey
+            else:
+                ip.user_ns[origname] = obj['val']
+                print "Restored", origname 
+
+def read_variables(ip, key=None):
+    db = ip.db
+    if key is None:
+        return None
+    else:
+        keys = db.keys('jot/'+key)
+    for key in keys:
+        # strip autorestore
+        justkey = os.path.basename(key)
+        print "restoring from ", justkey 
+        try:
+            obj = db[key]
+        except KeyError:
+            print "Unable to read variable '%s', ignoring (use %%jot -d to forget!)" % justkey
+            print "The error was:",sys.exc_info()[0]
+        else:
+            return obj
+
+
+def detail_variables(ip, key=None):
+    db, get = ip.db, ip.db.get
+ 
+    if key is None:
+        keys = db.keys('jot/*')
+    else:
+        keys = db.keys('jot/'+key)
+    if keys:
+        size = max(map(len,keys))
+    else:
+        size = 0
+
+    fmthead = '%-'+str(size)+'s [%s]'
+    fmtbody = 'Comment:\n %s'
+    fmtdata = 'Data:\n %s, %s'
+    for key in keys:
+        v = get(key,'<unavailable>')
+        justkey = os.path.basename(key)
+        try: 
+            print fmthead % (justkey, datetime.ctime(v.get('time','<unavailable>')))
+            print fmtbody % (v.get('comment','<unavailable>'))
+            d = v.get('val','unavailable')
+            print fmtdata % (repr(type(d)), '')
+            print repr(d)[0:200]
+            print
+            print
+        except AttributeError:
+            print fmt % (justkey, '<unavailable>', '<unavailable>', repr(v)[:50])
+
+
+def intm(n):
+    try:
+        return int(n)
+    except:
+        return 0
+
+def jot_obj(self, obj, name, comment=''):
+    """
+    write obj data to the note database, with whatever that should be noted.
+    """
+    had = self.db.keys('jot/'+name+'*')
+    # if it the same name but a later version, we stupidly add a number to the 
+    # so the name doesn't collide. Any better idea?
+    suffix = ''
+    if len(had)>0:
+        pre = os.path.commonprefix(had)
+        suf = [n.split(pre)[1] for n in had]
+        versions = map(intm, suf)
+        suffix = str(max(versions)+1)
+
+    uname = 'jot/'+name+suffix
+
+    # which one works better? 
+    #all = ip.IP.shadowhist.all()
+    all = ip.IP.shell.input_hist
+
+    # We may actually want to make snapshot of files that are run-ned.
+
+    # get the comment 
+    try:
+        comment = ip.IP.magic_edit('-x').strip()
+    except:
+        print "No comment is recorded."
+        comment = ''
+
+    self.db[uname] = Struct({'val':obj, 
+                'time'  :   datetime.now(), 
+                'hist'  :   all,
+                'name'  :   name,
+                'comment' : comment,})
+
+    print "Jotted down notes for '%s' (%s)" % (uname, obj.__class__.__name__)
+
+    
+
+def magic_jot(self, parameter_s=''):
+    """Lightweight persistence for python variables.
+
+    Example:
+    
+    ville@badger[~]|1> A = ['hello',10,'world']\\
+    ville@badger[~]|2> %jot A\\
+    ville@badger[~]|3> Exit
+    
+    (IPython session is closed and started again...)
+    
+    ville@badger:~$ ipython -p pysh\\
+    ville@badger[~]|1> print A
+    
+    ['hello', 10, 'world']
+    
+    Usage:
+    
+    %jot          - Show list of all variables and their current values\\
+    %jot -l       - Show list of all variables and their current values in detail\\
+    %jot -l <var> - Show one variable and its current values in detail\\
+    %jot <var>    - Store the *current* value of the variable to disk\\
+    %jot -d <var> - Remove the variable and its value from storage\\
+    %jot -z       - Remove all variables from storage (disabled)\\
+    %jot -r <var> - Refresh/Load variable from jot (delete current vals)\\
+    %jot foo >a.txt  - Store value of foo to new file a.txt\\
+    %jot foo >>a.txt - Append value of foo to file a.txt\\   
+    
+    It should be noted that if you change the value of a variable, you
+    need to %note it again if you want to persist the new value.
+    
+    Note also that the variables will need to be pickleable; most basic
+    python types can be safely %stored.
+    
+    """
+    
+    opts,argsl = self.parse_options(parameter_s,'drzl',mode='string')
+    args = argsl.split(None,1)
+    ip = self.getapi()
+    db = ip.db
+    # delete
+    if opts.has_key('d'):
+        try:
+            todel = args[0]
+        except IndexError:
+            error('You must provide the variable to forget')
+        else:
+            try:
+                del db['jot/' + todel]
+            except:
+                error("Can't delete variable '%s'" % todel)
+    # reset the whole database
+    elif opts.has_key('z'):
+        print "reseting the whole database has been disabled."
+        #for k in db.keys('autorestore/*'):
+        #    del db[k]
+
+    elif opts.has_key('r'):
+        try:
+            toret = args[0]
+        except:
+            print "restoring all the variables jotted down..."
+            refresh_variables(ip)
+        else:
+            refresh_variables(ip, toret)
+
+    elif opts.has_key('l'):
+        try:
+            tolist = args[0]
+        except:
+            print "List details for all the items."
+            detail_variables(ip)
+        else:
+            print "Details for", tolist, ":"
+            detail_variables(ip, tolist)
+    
+    # run without arguments -> list noted variables & notes 
+    elif not args:
+        vars = self.db.keys('jot/*')
+        vars.sort()            
+        if vars:
+            size = max(map(len,vars)) - 4 
+        else:
+            size = 0
+            
+        print 'Variables and their in-db values:'
+        fmt = '%-'+str(size)+'s [%s] -> %s'
+        get = db.get
+        for var in vars:
+            justkey = os.path.basename(var)
+            v = get(var,'<unavailable>')
+            try: 
+                print fmt % (justkey,\
+                    datetime.ctime(v.get('time','<unavailable>')),\
+                    v.get('comment','<unavailable>')[:70].replace('\n',' '),)
+            except AttributeError:
+                print fmt % (justkey, '<unavailable>', '<unavailable>', repr(v)[:50])
+
+    
+    # default action - store the variable
+    else:
+        # %store foo >file.txt or >>file.txt
+        if len(args) > 1 and args[1].startswith('>'):
+            fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
+            if args[1].startswith('>>'):
+                fil = open(fnam,'a')
+            else:
+                fil = open(fnam,'w')
+            obj = ip.ev(args[0])
+            print "Writing '%s' (%s) to file '%s'." % (args[0],
+              obj.__class__.__name__, fnam)
+
+            
+            if not isinstance (obj,basestring):
+                from pprint import pprint
+                pprint(obj,fil)
+            else:
+                fil.write(obj)
+                if not obj.endswith('\n'):
+                    fil.write('\n')
+            
+            fil.close()
+            return
+        
+        # %note foo
+        try:
+            obj = ip.user_ns[args[0]]
+        except KeyError:
+            # this should not be alias, for aliases, use %store
+            print
+            print "Error: %s doesn't exist." % args[0]
+            print 
+            print "Use %note -r <var> to retrieve variables. This should not be used " +\
+                  "to store alias, for saving aliases, use %store" 
+            return
+        else:
+            if isinstance(inspect.getmodule(obj), FakeModule):
+                print textwrap.dedent("""\
+                Warning:%s is %s 
+                Proper storage of interactively declared classes (or instances
+                of those classes) is not possible! Only instances
+                of classes in real modules on file system can be %%store'd.
+                """ % (args[0], obj) ) 
+                return
+            #pickled = pickle.dumps(obj)
+            #self.db[ 'jot/' + args[0] ] = obj
+            jot_obj(self, obj, args[0])
+
+
+def magic_read(self, parameter_s=''):
+    """    
+    %read <var> - Load variable from data that is jotted down.\\
+    
+    """
+    
+    opts,argsl = self.parse_options(parameter_s,'drzl',mode='string')
+    args = argsl.split(None,1)
+    ip = self.getapi()
+    db = ip.db
+    #if opts.has_key('r'):
+    try:
+        toret = args[0]
+    except:
+        print "which record do you want to read out?"
+        return
+    else:
+        return read_variables(ip, toret)
+
+
+ip.expose_magic('jot',magic_jot)
+ip.expose_magic('read',magic_read)

IPython/Extensions/ipy_lookfor.py

@@ -0,0 +1,234 b''
+"""
+IPython extension: %lookfor command for searching docstrings
+
+"""
+# Pauli Virtanen <[e-mail]>, 2008.
+
+import re, inspect, pkgutil, pydoc
+
+#------------------------------------------------------------------------------
+# Lookfor functionality
+#------------------------------------------------------------------------------
+
+# Cache for lookfor: {id(module): {name: (docstring, kind, index), ...}...}
+# where kind: "func", "class", "module", "object"
+# and index: index in breadth-first namespace traversal
+_lookfor_caches = {}
+
+# regexp whose match indicates that the string may contain a function signature
+_function_signature_re = re.compile(r"[a-z_]+\(.*[,=].*\)", re.I)
+
+def lookfor(what, modules=None, import_modules=True, regenerate=False):
+    """
+    Search for objects whose documentation contains all given words.
+    Shows a summary of matching objects, sorted roughly by relevance.
+
+    Parameters
+    ----------
+    what : str
+        String containing words to look for.
+
+    module : str, module
+        Module whose docstrings to go through.
+    import_modules : bool
+        Whether to import sub-modules in packages.
+        Will import only modules in __all__
+    regenerate: bool
+        Re-generate the docstring cache
+
+    """
+    # Cache
+    cache = {}
+    for module in modules:
+        try:
+            c = _lookfor_generate_cache(module, import_modules, regenerate)
+            cache.update(c)
+        except ImportError:
+            pass
+    
+    # Search
+    # XXX: maybe using a real stemming search engine would be better?
+    found = []
+    whats = str(what).lower().split()
+    if not whats: return
+
+    for name, (docstring, kind, index) in cache.iteritems():
+        if kind in ('module', 'object'): 
+            # don't show modules or objects
+            continue
+        ok = True
+        doc = docstring.lower()
+        for w in whats:
+            if w not in doc:
+                ok = False
+                break
+        if ok:
+            found.append(name)
+
+    # Relevance sort
+    # XXX: this is full Harrison-Stetson heuristics now,
+    # XXX: it probably could be improved
+
+    kind_relevance = {'func': 1000, 'class': 1000, 
+                      'module': -1000, 'object': -1000}
+
+    def relevance(name, docstr, kind, index):
+        r = 0
+        # do the keywords occur within the start of the docstring?
+        first_doc = "\n".join(docstr.lower().strip().split("\n")[:3])
+        r += sum([200 for w in whats if w in first_doc])
+        # do the keywords occur in the function name?
+        r += sum([30 for w in whats if w in name])
+        # is the full name long?
+        r += -len(name) * 5
+        # is the object of bad type?
+        r += kind_relevance.get(kind, -1000)
+        # is the object deep in namespace hierarchy?
+        r += -name.count('.') * 10
+        r += max(-index / 100, -100)
+        return r
+
+    def relevance_sort(a, b):
+        dr = relevance(b, *cache[b]) - relevance(a, *cache[a])
+        if dr != 0: return dr
+        else: return cmp(a, b)
+    found.sort(relevance_sort)
+
+    # Pretty-print
+    s = "Search results for '%s'" % (' '.join(whats))
+    help_text = [s, "-"*len(s)]
+    for name in found:
+        doc, kind, ix = cache[name]
+
+        doclines = [line.strip() for line in doc.strip().split("\n")
+                    if line.strip()]
+
+        # find a suitable short description
+        try:
+            first_doc = doclines[0].strip()
+            if _function_signature_re.search(first_doc):
+                first_doc = doclines[1].strip()
+        except IndexError:
+            first_doc = ""
+        help_text.append("%s\n    %s" % (name, first_doc))
+
+    # Output
+    if len(help_text) > 10:
+        pager = pydoc.getpager()
+        pager("\n".join(help_text))
+    else:
+        print "\n".join(help_text)
+
+def _lookfor_generate_cache(module, import_modules, regenerate):
+    """
+    Generate docstring cache for given module.
+
+    Parameters
+    ----------
+    module : str, None, module
+        Module for which to generate docstring cache
+    import_modules : bool
+        Whether to import sub-modules in packages.
+        Will import only modules in __all__
+    regenerate: bool
+        Re-generate the docstring cache
+
+    Returns
+    -------
+    cache : dict {obj_full_name: (docstring, kind, index), ...}
+        Docstring cache for the module, either cached one (regenerate=False)
+        or newly generated.
+        
+    """
+    global _lookfor_caches
+
+    if module is None:
+        module = "numpy"
+
+    if isinstance(module, str):
+        module = __import__(module)
+
+    if id(module) in _lookfor_caches and not regenerate:
+        return _lookfor_caches[id(module)]
+
+    # walk items and collect docstrings
+    cache = {}
+    _lookfor_caches[id(module)] = cache
+    seen = {}
+    index = 0
+    stack = [(module.__name__, module)]
+    while stack:
+        name, item = stack.pop(0)
+        if id(item) in seen: continue
+        seen[id(item)] = True
+
+        index += 1
+        kind = "object"
+       
+        if inspect.ismodule(item):
+            kind = "module"
+            try:
+                _all = item.__all__
+            except AttributeError:
+                _all = None
+            # import sub-packages
+            if import_modules and hasattr(item, '__path__'):
+                for m in pkgutil.iter_modules(item.__path__):
+                    if _all is not None and m[1] not in _all:
+                        continue
+                    try:
+                        __import__("%s.%s" % (name, m[1]))
+                    except ImportError:
+                        continue
+            for n, v in inspect.getmembers(item):
+                if _all is not None and n not in _all:
+                    continue
+                stack.append(("%s.%s" % (name, n), v))
+        elif inspect.isclass(item):
+            kind = "class"
+            for n, v in inspect.getmembers(item):
+                stack.append(("%s.%s" % (name, n), v))
+        elif callable(item):
+            kind = "func"
+        
+        doc = inspect.getdoc(item)
+        if doc is not None:
+            cache[name] = (doc, kind, index)
+
+    return cache
+
+#------------------------------------------------------------------------------
+# IPython connectivity
+#------------------------------------------------------------------------------
+
+import IPython.ipapi
+ip = IPython.ipapi.get()
+
+_lookfor_modules = ['numpy', 'scipy']
+
+def lookfor_f(self, arg=''):
+    r"""
+    Search for objects whose documentation contains all given words.
+    Shows a summary of matching objects, sorted roughly by relevance.
+
+    Usage
+    -----
+    %lookfor +numpy  some words
+    Search module 'numpy'
+
+    %lookfor_modules numpy scipy
+    Set default modules whose docstrings to search
+
+    """
+    lookfor(arg, modules=_lookfor_modules)
+
+def lookfor_modules_f(self, arg=''):
+    global _lookfor_modules
+    if not arg:
+        print "Modules included in %lookfor search:", _lookfor_modules
+    else:
+        _lookfor_modules = arg.split()
+
+ip.expose_magic('lookfor', lookfor_f)
+ip.expose_magic('lookfor_modules', lookfor_modules_f)
+

IPython/Extensions/ipy_vimserver.py

@@ -0,0 +1,239 b''
+""" Integration with gvim, by Erich Heine
+
+Provides a %vim magic command, and reuses the same vim session. Uses 
+unix domain sockets for communication between vim and IPython. ipy.vim is 
+available in doc/examples of the IPython distribution.
+
+Slightly touched up email announcement (and description how to use it) by 
+Erich Heine is here:
+
+Ive recently been playing with ipython, and like it quite a bit. I did
+however discover a bit of frustration, namely with editor interaction.
+I am a gvim user, and using the command edit on a new file causes
+ipython to try and run that file as soon as the text editor opens
+up. The -x command of course fixes this, but its still a bit annoying,
+switching windows to do a run file, then back to the text
+editor. Being a heavy tab user in gvim, another annoyance is not being
+able to specify weather a new tab is how I choose to open the file.
+
+Not being one to shirk my open source duties (and seeing this as a
+good excuse to poke around ipython internals), Ive created a script
+for having gvim and ipython work very nicely together. Ive attached
+both to this email (hoping of course that the mailing list allows such
+things).
+
+There are 2 files: 
+
+ipy_vimserver.py -- this file contains the ipython stuff
+ipy.vim -- this file contains the gvim stuff
+
+In combination they allow for a few functionalities:
+
+#1. the vim magic command. This is a fancy wrapper around the edit
+magic, that allows for a new option, -t, which opens the text in a new
+gvim tab.  Otherwise it works the same as edit -x. (it internally
+calls edit -x). This magic command also juggles vim server management,
+so when it is called when there is not a gvim running, it creates a
+new gvim instance, named after the ipython session name.  Once such a
+gvim instance is running, it will be used for subsequent uses of the
+vim command.
+
+#2. ipython - gvim interaction. Once a file has been opened with the
+vim magic (and a session set up, see below), pressing the F5 key in
+vim will cause the calling ipython instance to execute run
+filename.py. (if you typo like I do, this is very useful)
+
+#3. ipython server - this is a thread wich listens on a unix domain
+socket, and runs commands sent to that socket.
+
+Note, this only works on POSIX systems, that allow for AF_UNIX type
+sockets. It has only been tested on linux (a fairly recent debian
+testing distro).
+
+To install it put, the ipserver.py in your favorite locaion for
+sourcing ipython scripts. I put the ipy.vim in
+~/.vim/after/ftplugin/python/.
+
+To use (this can be scripted im sure, but i usually have 2 or 3
+ipythons and corresponding gvims open):
+
+import ipy_vimserver
+ipy_vimserver.setup('sessionname')
+
+(Editors note - you can probably add these to your ipy_user_conf.py)
+
+Then use ipython as you normally would, until you need to edit
+something. Instead of edit, use the vim magic.  Thats it!
+
+"""
+
+import IPython.ipapi
+#import ipythonhooks
+import socket, select
+import os, threading, subprocess
+import re
+
+ERRCONDS = select.POLLHUP|select.POLLERR
+SERVER = None
+ip = IPython.ipapi.get()
+
+# this listens to a unix domain socket in a separate thread, so that comms
+# between a vim instance and ipython can happen in a fun and productive way
+class IpyServer(threading.Thread):
+    def __init__(self, sname):
+        super(IpyServer, self).__init__()
+        self.keep_running = True
+        self.__sname = sname
+        self.socket = socket.socket(socket.AF_UNIX)
+        self.poller = select.poll()
+        self.current_conns = dict()
+        self.setDaemon(True)
+
+    def listen(self):
+        self.socket.bind(self.__sname)
+        self.socket.listen(1)
+
+    def __handle_error(self, socket):
+        if socket == self.socket.fileno():
+            self.keep_running = False
+            for a in self.current_conns.values():
+                a.close()
+            return False
+        else:
+            y = self.current_conns[socket]
+            del self.current_conns[socket]
+        y.close()
+        self.poller.unregister(socket)
+
+    def serve_me(self):
+        self.listen()
+        self.poller.register(self.socket,select.POLLIN|ERRCONDS)
+
+        while self.keep_running:
+            try:
+                avail = self.poller.poll(1)
+            except:
+                continue
+
+            if not avail: continue
+
+            for sock, conds in avail:
+                if conds & (ERRCONDS):
+                    if self.__handle_error(sock): continue
+                    else: break
+
+                if sock == self.socket.fileno():
+                    y = self.socket.accept()[0]
+                    self.poller.register(y, select.POLLIN|ERRCONDS)
+                    self.current_conns[y.fileno()] = y
+                else: y = self.current_conns.get(sock)
+
+                self.handle_request(y)
+
+        os.remove(self.__sname)
+
+    run = serve_me
+
+    def stop(self):
+        self.keep_running = False
+
+    def handle_request(self,sock):
+        sock.settimeout(1)
+        while self.keep_running:
+            try:
+                x = sock.recv(4096)
+            except socket.timeout:
+                pass
+            else:
+                break
+        self.do_it(x)
+
+    def do_it(self, data):
+        data = data.split('\n')
+        cmds = list()
+        for line in data:
+            cmds.append(line)
+        ip.runlines(cmds)
+
+
+# try to help ensure that the unix domain socket is cleaned up proper
+def shutdown_server(self):
+    if SERVER:
+        SERVER.stop()
+        SERVER.join(3)
+    raise IPython.ipapi.TryNext
+
+ip.set_hook('shutdown_hook', shutdown_server, 10)
+
+# this fun function exists to make setup easier for all, and makes the
+# vimhook function ready for instance specific communication
+def setup(sessionname='',socketdir=os.path.expanduser('~/.ipython/')):
+    global SERVER
+
+    if sessionname:
+        session = sessionname
+    elif os.environ.get('IPY_SESSION'):
+        session = os.environ.get('IPY_SESSION')
+    else:
+        session = 'IPYS'
+    vimhook.vimserver=session
+    vimhook.ipyserver = os.path.join(socketdir, session)
+    if not SERVER:
+        SERVER = IpyServer(vimhook.ipyserver)
+        SERVER.start()
+
+
+
+# calls gvim, with all ops happening on the correct gvim instance for this
+# ipython instance. it then calls edit -x (since gvim will return right away)
+# things of note: it sets up a special environment, so that the ipy.vim script
+# can connect back to the ipython instance and do fun things, like run the file
+def vimhook(self, fname, line):
+    env = os.environ.copy()
+    vserver = vimhook.vimserver.upper()
+    check = subprocess.Popen('gvim --serverlist', stdout = subprocess.PIPE,
+        shell=True)
+    check.wait()
+    cval = [l for l in check.stdout.readlines() if vserver in l]
+
+    if cval:
+        vimargs = '--remote%s' % (vimhook.extras,)
+    else:
+        vimargs = ''
+    vimhook.extras = ''
+
+    env['IPY_SESSION'] = vimhook.vimserver
+    env['IPY_SERVER'] = vimhook.ipyserver
+
+    if line is None: line = ''
+    else: line = '+' + line
+    vim_cmd = 'gvim --servername %s %s %s %s' % (vimhook.vimserver, vimargs,
+        line, fname)
+    subprocess.call(vim_cmd, env=env, shell=True)
+
+
+#default values to keep it sane...
+vimhook.vimserver = ''
+vimhook.ipyserver = ''
+
+ip.set_hook('editor',vimhook)
+
+# this is set up so more vim specific commands can be added, instead of just
+# the current -t. all thats required is a compiled regex, a call to do_arg(pat)
+# and the logic to deal with the new feature
+newtab = re.compile(r'-t(?:\s|$)')
+def vim(self, argstr):
+    def do_arg(pat, rarg):
+        x = len(pat.findall(argstr))
+        if x:
+            a = pat.sub('',argstr)
+            return rarg, a
+        else: return '', argstr
+
+    t, argstr = do_arg(newtab, '-tab')
+    vimhook.extras = t
+    argstr = 'edit -x ' + argstr
+    ip.magic(argstr)
+
+ip.expose_magic('vim', vim)
+

IPython/Extensions/ipy_winpdb.py

@@ -0,0 +1,73 b''
+""" Debug a script (like %run -d) in IPython process, Using WinPdb
+
+Usage:
+
+%wdb test.py
+    run test.py, with a winpdb breakpoint at start of the file 
+    
+%wdb pass
+    Change the password (e.g. if you have forgotten the old one)
+"""
+
+import os
+
+import IPython.ipapi
+import rpdb2
+
+ip = IPython.ipapi.get()
+
+rpdb_started = False
+
+def wdb_f(self, arg):
+    """ Debug a script (like %run -d) in IPython process, Using WinPdb
+    
+    Usage:
+    
+    %wdb test.py
+        run test.py, with a winpdb breakpoint at start of the file 
+        
+    %wdb pass
+        Change the password (e.g. if you have forgotten the old one)
+        
+    Note that after the script has been run, you need to do "Go" (f5) 
+    in WinPdb to resume normal IPython operation.
+    """
+
+    global rpdb_started
+    if not arg.strip():
+        print __doc__
+        return
+        
+    if arg.strip() == 'pass':
+        passwd = raw_input('Enter new winpdb session password: ')
+        ip.db['winpdb_pass'] = passwd
+        print "Winpdb password changed"
+        if rpdb_started:
+            print "You need to restart IPython to use the new password"
+        return 
+    
+    path = os.path.abspath(arg)
+    if not os.path.isfile(path):
+        raise IPython.ipapi.UsageError("%%wdb: file %s does not exist" % path)
+    if not rpdb_started:
+        passwd = ip.db.get('winpdb_pass', None)
+        if passwd is None:
+            import textwrap
+            print textwrap.dedent("""\
+            Winpdb sessions need a password that you use for attaching the external
+            winpdb session. IPython will remember this. You can change the password later 
+            by '%wpdb pass'
+            """)
+            passwd = raw_input('Enter new winpdb session password: ')
+            ip.db['winpdb_pass'] = passwd
+            
+        print "Starting rpdb2 in IPython process"
+        rpdb2.start_embedded_debugger(passwd, timeout = 0)
+        rpdb_started = True
+        
+    rpdb2.set_temp_breakpoint(path)
+    print 'It is time to attach with WinPdb (launch WinPdb if needed, File -> Attach)'
+    ip.magic('%run ' + arg)
+    
+
+ip.expose_magic('wdb', wdb_f)

IPython/gui/wx/ipshell_nonblocking.py

@@ -0,0 +1,460 b''
+#!/usr/bin/python
+# -*- coding: iso-8859-15 -*-
+'''
+Provides IPython remote instance.
+
+@author: Laurent Dufrechou
+laurent.dufrechou _at_ gmail.com
+@license: BSD
+
+All rights reserved. This program and the accompanying materials are made
+available under the terms of the BSD which accompanies this distribution, and
+is available at U{http://www.opensource.org/licenses/bsd-license.php}
+'''
+
+__version__ = 0.9
+__author__  = "Laurent Dufrechou"
+__email__   = "laurent.dufrechou _at_ gmail.com"
+__license__ = "BSD"
+
+import re
+import sys
+import os
+import locale
+import time
+import pydoc,__builtin__,site
+from thread_ex import ThreadEx
+from StringIO import StringIO
+
+try:
+        import IPython
+except Exception,e:
+        raise "Error importing IPython (%s)" % str(e)
+
+##############################################################################
+class _Helper(object):
+    """Redefine the built-in 'help'.
+    This is a wrapper around pydoc.help (with a twist).
+    """
+
+    def __init__(self,pager):
+        self._pager = pager
+
+    def __repr__(self):
+        return "Type help() for interactive help, " \
+               "or help(object) for help about object."
+    
+    def __call__(self, *args, **kwds):
+        class DummyWriter(object):
+            def __init__(self,pager):
+                self._pager = pager
+                
+            def write(self,data):
+                self._pager(data)
+
+        import pydoc
+        pydoc.help.output = DummyWriter(self._pager)
+        pydoc.help.interact = lambda :1
+        
+        return pydoc.help(*args, **kwds)
+
+  
+##############################################################################
+class _CodeExecutor(ThreadEx):
+    
+    def __init__(self, instance, after):
+        ThreadEx.__init__(self)
+        self.instance = instance
+        self._afterExecute=after
+
+    def run(self):
+        try:
+            self.instance._doc_text = None
+            self.instance._help_text = None
+            self.instance._execute()
+            # used for uper class to generate event after execution
+            self._afterExecute() 
+            
+        except KeyboardInterrupt:
+            pass
+ 
+
+##############################################################################
+class NonBlockingIPShell(object):
+    '''
+    Create an IPython instance, running the commands in a separate,
+    non-blocking thread. 
+    This allows embedding in any GUI without blockage.
+
+    Note: The ThreadEx class supports asynchroneous function call
+          via raise_exc()
+    '''
+
+    def __init__(self,argv=[],user_ns={},user_global_ns=None,
+                 cin=None, cout=None, cerr=None,
+                 ask_exit_handler=None):
+        '''
+        @param argv: Command line options for IPython
+        @type argv: list
+        @param user_ns: User namespace.
+        @type user_ns: dictionary
+        @param user_global_ns: User global namespace.
+        @type user_global_ns: dictionary.
+        @param cin: Console standard input.
+        @type cin: IO stream
+        @param cout: Console standard output.
+        @type cout: IO stream
+        @param cerr: Console standard error.
+        @type cerr: IO stream
+        @param exit_handler: Replacement for builtin exit() function
+        @type exit_handler: function
+        @param time_loop: Define the sleep time between two thread's loop
+        @type int
+        '''
+        #ipython0 initialisation
+        self.initIpython0(argv, user_ns, user_global_ns,
+                          cin, cout, cerr,
+                          ask_exit_handler)
+        
+        #vars used by _execute
+        self._iter_more = 0
+        self._history_level = 0
+        self._complete_sep =  re.compile('[\s\{\}\[\]\(\)\=]')
+        self._prompt = str(self._IP.outputcache.prompt1).strip()
+
+        #thread working vars
+        self._line_to_execute = ''
+
+        #vars that will be checked by GUI loop to handle thread states...
+        #will be replaced later by PostEvent GUI funtions...
+        self._doc_text = None
+        self._help_text = None
+        self._add_button = None
+
+    def initIpython0(self, argv=[], user_ns={}, user_global_ns=None,
+                     cin=None, cout=None, cerr=None,
+                     ask_exit_handler=None):
+        #first we redefine in/out/error functions of IPython 
+        if cin:
+            IPython.Shell.Term.cin = cin
+        if cout:
+            IPython.Shell.Term.cout = cout
+        if cerr:
+            IPython.Shell.Term.cerr = cerr
+        
+        # This is to get rid of the blockage that accurs during
+        # IPython.Shell.InteractiveShell.user_setup()
+        IPython.iplib.raw_input = lambda x: None
+
+        self._term = IPython.genutils.IOTerm(cin=cin, cout=cout, cerr=cerr)
+
+        excepthook = sys.excepthook
+
+        self._IP = IPython.Shell.make_IPython(
+                                            argv,user_ns=user_ns,
+                                            user_global_ns=user_global_ns,
+                                            embedded=True,
+                                            shell_class=IPython.Shell.InteractiveShell)
+
+        #we replace IPython default encoding by wx locale encoding
+        loc = locale.getpreferredencoding()
+        if loc:
+                self._IP.stdin_encoding = loc
+        #we replace the ipython default pager by our pager
+        self._IP.set_hook('show_in_pager',self._pager)
+        
+        #we replace the ipython default shell command caller by our shell handler
+        self._IP.set_hook('shell_hook',self._shell)
+        
+        #we replace the ipython default input command caller by our method
+        IPython.iplib.raw_input_original = self._raw_input
+        #we replace the ipython default exit command by our method
+        self._IP.exit = ask_exit_handler
+        #we replace the help command
+        self._IP.user_ns['help'] = _Helper(self._pager_help)
+
+        #we disable cpase magic... until we found a way to use it properly.
+        #import IPython.ipapi
+        ip = IPython.ipapi.get()
+        def bypassMagic(self, arg):
+            print '%this magic is currently disabled.'
+        ip.expose_magic('cpaste', bypassMagic)
+        
+        sys.excepthook = excepthook
+
+    #----------------------- Thread management section ----------------------    
+    def doExecute(self,line):
+        """
+        Tell the thread to process the 'line' command
+        """
+
+        self._line_to_execute = line
+        #we launch the ipython line execution in a thread to make it interruptible
+        self.ce = _CodeExecutor(self,self._afterExecute)
+        self.ce.start()
+        
+    #----------------------- IPython management section ----------------------    
+    def getDocText(self):
+        """
+        Returns the output of the processing that need to be paged (if any)
+
+        @return: The std output string.
+        @rtype: string
+        """
+        return self._doc_text
+        
+    def getHelpText(self):
+        """
+        Returns the output of the processing that need to be paged via help pager(if any)
+
+        @return: The std output string.
+        @rtype: string
+        """
+        return self._help_text
+
+    def getBanner(self):
+        """
+        Returns the IPython banner for useful info on IPython instance
+
+        @return: The banner string.
+        @rtype: string
+        """
+        return self._IP.BANNER
+    
+    def getPromptCount(self):
+        """
+        Returns the prompt number.
+        Each time a user execute a line in the IPython shell the prompt count is increased
+
+        @return: The prompt number
+        @rtype: int
+        """
+        return self._IP.outputcache.prompt_count
+
+    def getPrompt(self):
+        """
+        Returns current prompt inside IPython instance
+        (Can be In [...]: ot ...:)
+
+        @return: The current prompt.
+        @rtype: string
+        """
+        return self._prompt
+
+    def getIndentation(self):
+        """
+        Returns the current indentation level
+        Usefull to put the caret at the good start position if we want to do autoindentation.
+
+        @return: The indentation level.
+        @rtype: int
+        """
+        return self._IP.indent_current_nsp
+        
+    def updateNamespace(self, ns_dict):
+        '''
+        Add the current dictionary to the shell namespace.
+
+        @param ns_dict: A dictionary of symbol-values.
+        @type ns_dict: dictionary
+        '''
+        self._IP.user_ns.update(ns_dict)
+
+    def complete(self, line):
+        '''
+        Returns an auto completed line and/or posibilities for completion.
+
+        @param line: Given line so far.
+        @type line: string
+
+        @return: Line completed as for as possible,
+        and possible further completions.
+        @rtype: tuple
+        '''
+        split_line = self._complete_sep.split(line)
+        possibilities = self._IP.complete(split_line[-1])
+        if possibilities:
+
+            def _commonPrefix(str1, str2):
+                '''
+                Reduction function. returns common prefix of two given strings.
+
+                @param str1: First string.
+                @type str1: string
+                @param str2: Second string
+                @type str2: string
+
+                @return: Common prefix to both strings.
+                @rtype: string
+                '''
+                for i in range(len(str1)):
+                    if not str2.startswith(str1[:i+1]):
+                        return str1[:i]
+                return str1
+            common_prefix = reduce(_commonPrefix, possibilities)
+            completed = line[:-len(split_line[-1])]+common_prefix
+        else:
+            completed = line
+        return completed, possibilities
+
+    def historyBack(self):
+        '''
+        Provides one history command back.
+
+        @return: The command string.
+        @rtype: string
+        '''
+        history = ''
+        #the below while loop is used to suppress empty history lines
+        while((history == '' or history == '\n') and self._history_level >0):
+                if self._history_level>=1:
+                        self._history_level -= 1
+                history = self._getHistory()            
+        return history
+
+    def historyForward(self):
+        '''
+        Provides one history command forward.
+
+        @return: The command string.
+        @rtype: string
+        '''
+        history = ''
+        #the below while loop is used to suppress empty history lines
+        while((history == '' or history == '\n') and self._history_level <= self._getHistoryMaxIndex()):
+                if self._history_level < self._getHistoryMaxIndex():
+                        self._history_level += 1
+                        history = self._getHistory()
+                else:
+                        if self._history_level == self._getHistoryMaxIndex():
+                                history = self._getHistory()
+                                self._history_level += 1
+                        else:
+                                history = ''
+        return history
+
+    def initHistoryIndex(self):
+        '''
+        set history to last command entered
+        '''
+        self._history_level = self._getHistoryMaxIndex()+1
+
+    #----------------------- IPython PRIVATE management section --------------
+    def _afterExecute(self):
+        '''
+        Can be redefined to generate post event after excution is done
+        '''
+        pass
+
+    #def _askExit(self):
+    #    '''
+    #    Can be redefined to generate post event to exit the Ipython shell
+    #    '''
+    #    pass
+
+    def _getHistoryMaxIndex(self):
+        '''
+        returns the max length of the history buffer
+
+        @return: history length
+        @rtype: int
+        '''
+        return len(self._IP.input_hist_raw)-1
+        
+    def _getHistory(self):
+        '''
+        Get's the command string of the current history level.
+
+        @return: Historic command stri
+        @rtype: string
+        '''
+        rv = self._IP.input_hist_raw[self._history_level].strip('\n')
+        return rv
+
+    def _pager_help(self,text):
+        '''
+        This function is used as a callback replacment to IPython help pager function
+
+        It puts the 'text' value inside the self._help_text string that can be retrived via getHelpText
+        function.
+        '''
+        if self._help_text == None:
+            self._help_text = text
+        else:
+            self._help_text += text
+    
+    def _pager(self,IP,text):
+        '''
+        This function is used as a callback replacment to IPython pager function
+
+        It puts the 'text' value inside the self._doc_text string that can be retrived via getDocText
+        function.
+        '''
+        self._doc_text = text
+    
+    def _raw_input(self, prompt=''):
+        '''
+        Custom raw_input() replacement. Get's current line from console buffer.
+
+        @param prompt: Prompt to print. Here for compatability as replacement.
+        @type prompt: string
+
+        @return: The current command line text.
+        @rtype: string
+        '''
+        return self._line_to_execute
+
+    def _execute(self):
+        '''
+        Executes the current line provided by the shell object.
+        '''
+        orig_stdout = sys.stdout
+        sys.stdout = IPython.Shell.Term.cout
+                
+        try:
+            line = self._IP.raw_input(None, self._iter_more)
+            if self._IP.autoindent:
+                self._IP.readline_startup_hook(None)
+
+        except KeyboardInterrupt:
+            self._IP.write('\nKeyboardInterrupt\n')
+            self._IP.resetbuffer()
+            # keep cache in sync with the prompt counter:
+            self._IP.outputcache.prompt_count -= 1
+
+            if self._IP.autoindent:
+                self._IP.indent_current_nsp = 0
+            self._iter_more = 0
+        except:
+            self._IP.showtraceback()
+        else:
+            self._iter_more = self._IP.push(line)
+            if (self._IP.SyntaxTB.last_syntax_error and
+                    self._IP.rc.autoedit_syntax):
+                self._IP.edit_syntax_error()
+        if self._iter_more:
+            self._prompt = str(self._IP.outputcache.prompt2).strip()
+            if self._IP.autoindent:
+                self._IP.readline_startup_hook(self._IP.pre_readline)
+        else:
+            self._prompt = str(self._IP.outputcache.prompt1).strip()
+            self._IP.indent_current_nsp = 0 #we set indentation to 0
+        sys.stdout = orig_stdout
+    
+    def _shell(self, ip, cmd):
+        '''
+        Replacement method to allow shell commands without them blocking.
+
+        @param ip: Ipython instance, same as self._IP
+        @type cmd: Ipython instance
+        @param cmd: Shell command to execute.
+        @type cmd: string
+        '''
+        stdin, stdout = os.popen4(cmd)
+        result = stdout.read().decode('cp437').encode(locale.getpreferredencoding())
+        #we use print command because the shell command is called inside IPython instance and thus is
+        #redirected to thread cout
+        #"\x01\x1b[1;36m\x02" <-- add colour to the text...
+        print "\x01\x1b[1;36m\x02"+result
+        stdout.close()
+        stdin.close()

IPython/gui/wx/options.conf

@@ -0,0 +1,6 b''
+completion=IPYTHON
+background_color=BLACK
+filter_empty=True
+filter_magic=True
+filter_doc=True
+filter_cmd=True

IPython/shellglobals.py

@@ -0,0 +1,96 b''
+from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
+
+import thread,inspect
+
+try:
+    import ctypes
+    HAS_CTYPES = True
+except ImportError:
+    HAS_CTYPES = False
+
+
+# Globals
+# global flag to pass around information about Ctrl-C without exceptions
+KBINT = False
+
+# global flag to turn on/off Tk support.
+USE_TK = False
+
+# ID for the main thread, used for cross-thread exceptions
+MAIN_THREAD_ID = thread.get_ident()
+
+# Tag when runcode() is active, for exception handling
+CODE_RUN = None
+
+
+#-----------------------------------------------------------------------------
+# This class is trivial now, but I want to have it in to publish a clean
+# interface. Later when the internals are reorganized, code that uses this
+# shouldn't have to change.
+
+
+if HAS_CTYPES:
+    #  Add async exception support.  Trick taken from:
+    # http://sebulba.wikispaces.com/recipe+thread2
+    def _async_raise(tid, exctype):
+        """raises the exception, performs cleanup if needed"""
+        if not inspect.isclass(exctype):
+            raise TypeError("Only types can be raised (not instances)")
+        res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid,
+                                                         ctypes.py_object(exctype))
+        if res == 0:
+            raise ValueError("invalid thread id")
+        elif res != 1:
+            # """if it returns a number greater than one, you're in trouble, 
+            # and you should call it again with exc=NULL to revert the effect"""
+            ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, 0)
+            raise SystemError("PyThreadState_SetAsyncExc failed")
+
+    def sigint_handler (signum,stack_frame):
+        """Sigint handler for threaded apps.
+
+        This is a horrible hack to pass information about SIGINT _without_
+        using exceptions, since I haven't been able to properly manage
+        cross-thread exceptions in GTK/WX.  In fact, I don't think it can be
+        done (or at least that's my understanding from a c.l.py thread where
+        this was discussed)."""
+
+        global KBINT
+
+        if CODE_RUN:
+            _async_raise(MAIN_THREAD_ID,KeyboardInterrupt)
+        else:
+            KBINT = True
+            print '\nKeyboardInterrupt - Press <Enter> to continue.',
+            Term.cout.flush()
+
+else:
+    def sigint_handler (signum,stack_frame):
+        """Sigint handler for threaded apps.
+
+        This is a horrible hack to pass information about SIGINT _without_
+        using exceptions, since I haven't been able to properly manage
+        cross-thread exceptions in GTK/WX.  In fact, I don't think it can be
+        done (or at least that's my understanding from a c.l.py thread where
+        this was discussed)."""
+
+        global KBINT
+
+        print '\nKeyboardInterrupt - Press <Enter> to continue.',
+        Term.cout.flush()
+        # Set global flag so that runsource can know that Ctrl-C was hit
+        KBINT = True
+
+def run_in_frontend(src):
+    """ Check if source snippet can be run in the REPL thread, as opposed to GUI mainloop
+    
+    (to prevent unnecessary hanging of mainloop).  
+    
+    """
+    
+    if src.startswith('_ip.system(') and not '\n' in src:
+        return True
+    return False
+    
+    
+    

IPython/twshell.py

@@ -0,0 +1,278 b''
+import sys
+
+from twisted.internet import reactor, threads
+
+from IPython.ipmaker import make_IPython
+from IPython.iplib import InteractiveShell 
+from IPython.ipstruct import Struct
+import Queue,thread,threading,signal
+from signal import signal, SIGINT
+from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
+import shellglobals
+
+def install_gtk2():
+    """ Install gtk2 reactor, needs to be called bef """
+    from twisted.internet import gtk2reactor
+    gtk2reactor.install()
+
+
+def hijack_reactor():
+    """Modifies Twisted's reactor with a dummy so user code does
+    not block IPython.  This function returns the original
+    'twisted.internet.reactor' that has been hijacked.
+
+    NOTE: Make sure you call this *AFTER* you've installed
+    the reactor of your choice.
+    """
+    from twisted import internet
+    orig_reactor = internet.reactor
+
+    class DummyReactor(object):
+        def run(self):
+            pass
+        def __getattr__(self, name):
+            return getattr(orig_reactor, name)
+        def __setattr__(self, name, value):
+            return setattr(orig_reactor, name, value)
+    
+    internet.reactor = DummyReactor()
+    return orig_reactor
+
+class TwistedInteractiveShell(InteractiveShell):
+    """Simple multi-threaded shell."""
+
+    # Threading strategy taken from:
+    # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/65109, by Brian
+    # McErlean and John Finlay.  Modified with corrections by Antoon Pardon,
+    # from the pygtk mailing list, to avoid lockups with system calls.
+
+    # class attribute to indicate whether the class supports threads or not.
+    # Subclasses with thread support should override this as needed.
+    isthreaded = True
+
+    def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
+                 user_ns=None,user_global_ns=None,banner2='',**kw):
+        """Similar to the normal InteractiveShell, but with threading control"""
+        
+        InteractiveShell.__init__(self,name,usage,rc,user_ns,
+                                  user_global_ns,banner2)
+
+
+        # A queue to hold the code to be executed. 
+        self.code_queue = Queue.Queue()
+
+        # Stuff to do at closing time
+        self._kill = None
+        on_kill = kw.get('on_kill', [])
+        # Check that all things to kill are callable:
+        for t in on_kill:
+            if not callable(t):
+                raise TypeError,'on_kill must be a list of callables'
+        self.on_kill = on_kill
+        # thread identity of the "worker thread" (that may execute code directly)
+        self.worker_ident = None
+        self.reactor_started = False
+        self.first_run = True
+        
+    def runsource(self, source, filename="<input>", symbol="single"):
+        """Compile and run some source in the interpreter.
+
+        Modified version of code.py's runsource(), to handle threading issues.
+        See the original for full docstring details."""
+        
+        # If Ctrl-C was typed, we reset the flag and return right away
+        if shellglobals.KBINT:
+            shellglobals.KBINT = False
+            return False
+
+        if self._kill:
+            # can't queue new code if we are being killed
+            return True
+        
+        try:
+            code = self.compile(source, filename, symbol)
+        except (OverflowError, SyntaxError, ValueError):
+            # Case 1
+            self.showsyntaxerror(filename)
+            return False
+
+        if code is None:
+            # Case 2
+            return True
+
+        # shortcut - if we are in worker thread, or the worker thread is not running, 
+        # execute directly (to allow recursion and prevent deadlock if code is run early 
+        # in IPython construction)
+        
+        if (not self.reactor_started or (self.worker_ident is None and not self.first_run) 
+            or self.worker_ident == thread.get_ident() or shellglobals.run_in_frontend(source)):
+            InteractiveShell.runcode(self,code)
+            return
+
+        # Case 3
+        # Store code in queue, so the execution thread can handle it.
+ 
+        self.first_run = False
+        completed_ev, received_ev = threading.Event(), threading.Event() 
+        
+        self.code_queue.put((code,completed_ev, received_ev))
+
+        reactor.callLater(0.0,self.runcode)
+        received_ev.wait(5)
+        if not received_ev.isSet():
+            # the mainloop is dead, start executing code directly
+            print "Warning: Timeout for mainloop thread exceeded"
+            print "switching to nonthreaded mode (until mainloop wakes up again)"
+            self.worker_ident = None
+        else:            
+            completed_ev.wait()
+        
+        return False
+
+    def runcode(self):
+        """Execute a code object.
+
+        Multithreaded wrapper around IPython's runcode()."""
+        
+        
+        # we are in worker thread, stash out the id for runsource() 
+        self.worker_ident = thread.get_ident()
+
+        if self._kill:
+            print >>Term.cout, 'Closing threads...',
+            Term.cout.flush()
+            for tokill in self.on_kill:
+                tokill()
+            print >>Term.cout, 'Done.'
+            # allow kill() to return
+            self._kill.set()
+            return True
+
+        # Install SIGINT handler.  We do it every time to ensure that if user
+        # code modifies it, we restore our own handling.
+        try:
+            pass
+            signal(SIGINT,shellglobals.sigint_handler)
+        except SystemError:
+            # This happens under Windows, which seems to have all sorts
+            # of problems with signal handling.  Oh well...
+            pass
+
+        # Flush queue of pending code by calling the run methood of the parent
+        # class with all items which may be in the queue.
+        code_to_run = None
+        while 1:
+            try:
+                code_to_run, completed_ev, received_ev = self.code_queue.get_nowait()                
+            except Queue.Empty:
+                break
+            received_ev.set()
+
+            
+            # Exceptions need to be raised differently depending on which
+            # thread is active.  This convoluted try/except is only there to
+            # protect against asynchronous exceptions, to ensure that a shellglobals.KBINT
+            # at the wrong time doesn't deadlock everything.  The global
+            # CODE_TO_RUN is set to true/false as close as possible to the
+            # runcode() call, so that the KBINT handler is correctly informed.
+            try:
+                try:
+                   shellglobals.CODE_RUN = True
+                   InteractiveShell.runcode(self,code_to_run)
+                except KeyboardInterrupt:
+                   print "Keyboard interrupted in mainloop"
+                   while not self.code_queue.empty():
+                      code = self.code_queue.get_nowait()
+                   break
+            finally:
+                shellglobals.CODE_RUN = False
+                # allow runsource() return from wait
+                completed_ev.set()                
+        
+        # This MUST return true for gtk threading to work
+        return True
+
+    def kill(self):
+        """Kill the thread, returning when it has been shut down."""
+        self._kill = threading.Event()
+        reactor.callLater(0.0,self.runcode)
+        self._kill.wait()
+
+
+
+class IPShellTwisted:
+    """Run a Twisted reactor while in an IPython session.
+
+    Python commands can be passed to the thread where they will be
+    executed.  This is implemented by periodically checking for
+    passed code using a Twisted reactor callback.
+    """
+
+    TIMEOUT = 0.01 # Millisecond interval between reactor runs.
+
+    def __init__(self, argv=None, user_ns=None, debug=1,
+                 shell_class=TwistedInteractiveShell):
+
+        from twisted.internet import reactor
+        self.reactor = hijack_reactor()
+
+        mainquit = self.reactor.stop
+
+        # Make sure IPython keeps going after reactor stop.
+        def reactorstop():
+            pass
+        self.reactor.stop = reactorstop
+        reactorrun_orig = self.reactor.run
+        self.quitting = False
+        def reactorrun():
+            while True and not self.quitting:
+                reactorrun_orig()
+        self.reactor.run = reactorrun
+        
+        self.IP = make_IPython(argv, user_ns=user_ns, debug=debug,
+                               shell_class=shell_class,
+                               on_kill=[mainquit])
+
+        # threading.Thread.__init__(self)
+
+    def run(self):
+        self.IP.mainloop()
+        self.quitting = True
+        self.IP.kill()
+
+    def mainloop(self):
+        def mainLoopThreadDeath(r):
+            print "mainLoopThreadDeath: ", str(r)
+        def spawnMainloopThread():
+            d=threads.deferToThread(self.run)
+            d.addBoth(mainLoopThreadDeath)
+        reactor.callWhenRunning(spawnMainloopThread)
+        self.IP.reactor_started = True
+        self.reactor.run()
+        print "mainloop ending...."   
+        
+exists = True
+
+
+if __name__ == '__main__':
+    # Sample usage.
+
+    # Create the shell object. This steals twisted.internet.reactor
+    # for its own purposes, to make sure you've already installed a
+    # reactor of your choice.
+    shell = IPShellTwisted(
+        argv=[],
+        user_ns={'__name__': '__example__',
+                 'hello': 'world',
+                 },
+        )
+
+    # Run the mainloop.  This runs the actual reactor.run() method.
+    # The twisted.internet.reactor object at this point is a dummy
+    # object that passes through to the actual reactor, but prevents
+    # run() from being called on it again.
+    shell.mainloop()
+
+    # You must exit IPython to terminate your program.
+    print 'Goodbye!'
+

debian/install

@@ -0,0 +1,1 b''
+doc/ipython.el		usr/share/emacs/site-lisp

debian/irunner.1

@@ -0,0 +1,52 b''
+.TH IRUNNER 1 "April 24, 2007" "" ""
+.SH NAME
+\fBirunner \- interactive runner interface
+.SH SYNOPSIS
+.nf
+.fam C
+\fBirunner\fP [\fIoptions\fP] \fIfile_to_run\fP
+.fam T
+.fi
+.SH DESCRIPTION
+irunner is an interface to the various interactive runners
+available in IPython's \fBirunner\fP module. 
+.PP
+The already implemented runners are listed below; adding
+one for a new program is a trivial task, see the source
+for examples.
+.SH OPTIONS
+.TP
+.B
+\-h, \-\-help
+show this help message and exit
+.TP
+.B
+\-\-ipython
+IPython interactive runner (default).
+.TP
+.B
+\-\-python
+Python interactive runner.
+.TP
+.B
+\-\-sage
+SAGE interactive runner.
+.SH EXAMPLE
+irunner.py \-\-python \-\- \-\-help
+will pass \-\-help to the python runner.
+Similarly,
+irunner.py \-\-ipython \-\- \-\-interact script.ipy
+.SH SEE ALSO
+.BR ipython(1)
+.br
+.SH BUGS
+The SAGE runner only works if you manually configure your SAGE
+copy to use 'colors NoColor' in the ipythonrc config file, since
+currently the prompt matching regexp does not identify color sequences.
+.SH AUTHOR
+\fBirunner\fP is an extension of Ken Schutte <kschutte-AT-csail.mit.edu>'s
+script contributed on the ipython-user list:
+http://scipy.net/pipermail/ipython-user/2006-May/001705.html
+.PP
+This manual page was written by Bernd Zeimetz <[e-mail]>,
+for the Debian project (but may be used by others).

debian/manpages

@@ -0,0 +1,1 b''
+debian/irunner.1

debian/pycompat

@@ -0,0 +1,1 b''
+2

debian/watch

@@ -0,0 +1,2 b''
+version=3
+http://ipython.scipy.org/dist/ ipython-(.*)\.tar\.gz

doc/do_sphinx.py

@@ -0,0 +1,74 b''
+#!/usr/bin/env python
+"""Script to build documentation using Sphinx.
+"""
+
+import fileinput,os,sys
+
+def oscmd(c):
+    os.system(c)
+
+# html manual.
+oscmd('sphinx-build -d build/doctrees source build/html')
+
+if sys.platform != 'win32':
+    # LaTeX format.
+    oscmd('sphinx-build -b latex -d build/doctrees source build/latex')
+
+    # Produce pdf.
+    topdir = os.getcwd()
+    os.chdir('build/latex')
+
+    # Change chapter style to section style: allows chapters to start on 
+    # the current page.  Works much better for the short chapters we have.
+    # This must go in the class file rather than the preamble, so we modify 
+    # manual.cls at runtime.
+    chapter_cmds=r'''
+% Local changes.
+\renewcommand\chapter{
+    \thispagestyle{plain}
+    \global\@topnum\z@
+    \@afterindentfalse
+    \secdef\@chapter\@schapter
+}
+\def\@makechapterhead#1{
+    \vspace*{10\p@}
+    {\raggedright \reset@font \Huge \bfseries \thechapter \quad #1}
+    \par\nobreak
+    \hrulefill
+    \par\nobreak
+    \vspace*{10\p@}
+}
+\def\@makeschapterhead#1{
+    \vspace*{10\p@}
+    {\raggedright \reset@font \Huge \bfseries #1}
+    \par\nobreak
+    \hrulefill
+    \par\nobreak
+    \vspace*{10\p@}
+}
+'''
+
+    unmodified=True
+    for line in fileinput.FileInput('manual.cls',inplace=1):
+        if 'Support for module synopsis' in line and unmodified:
+            line=chapter_cmds+line
+        elif 'makechapterhead' in line:
+            # Already have altered manual.cls: don't need to again.
+            unmodified=False
+        print line,
+
+    # Copying the makefile produced by sphinx...
+    oscmd('pdflatex ipython.tex')
+    oscmd('pdflatex ipython.tex')
+    oscmd('pdflatex ipython.tex')
+    oscmd('makeindex -s python.ist ipython.idx')
+    oscmd('makeindex -s python.ist modipython.idx')
+    oscmd('pdflatex ipython.tex')
+    oscmd('pdflatex ipython.tex')
+
+    # Create a manual/ directory with final html/pdf output
+    os.chdir(topdir)
+    oscmd('rm -rf manual')
+    oscmd('mkdir manual')
+    oscmd('cp -r build/html/*.html build/html/_static manual/')
+    oscmd('cp build/latex/ipython.pdf manual/')

doc/examples/ipy.vim

@@ -0,0 +1,67 b''
+if !exists("$IPY_SESSION")
+    finish
+endif
+
+" set up the python interpreter within vim, to have all the right modules
+" imported, as well as certain useful globals set
+python import socket
+python import os
+python import vim
+python IPYSERVER = None
+
+python << EOF
+# do we have a connection to the ipython instance?
+def check_server():
+    global IPYSERVER
+    if IPYSERVER:
+        return True
+    else:
+        return False
+
+# connect to the ipython server, if we need to
+def connect():
+    global IPYSERVER
+    if check_server():
+        return
+    try:
+        IPYSERVER = socket.socket(socket.AF_UNIX)
+        IPYSERVER.connect(os.environ.get('IPY_SERVER'))
+    except:
+        IPYSERVER = None
+
+def disconnect():
+    if IPYSERVER:
+        IPYSERVER.close()
+
+def send(cmd):
+    x = 0
+    while True:
+        x += IPYSERVER.send(cmd)
+        if x < len(cmd):
+            cmd = cmd[x:]
+        else:
+            break
+
+def run_this_file():
+    if check_server():
+        send('run %s' % (vim.current.buffer.name,))
+    else:
+        raise Exception, "Not connected to an IPython server"
+EOF
+
+fun! <SID>toggle_send_on_save()
+    if exists("s:ssos") && s:ssos == 1
+        let s:ssos = 0
+        au! BufWritePost *.py :py run_this_file()
+        echo "Autosend Off"
+    else
+        let s:ssos = 1
+        au BufWritePost *.py :py run_this_file()
+        echo "Autowsend On"
+    endif
+endfun
+
+map <silent> <F5> :python run_this_file()<CR>
+imap <silent> <C-F5> <ESC><F5>a
+map <F7> :call <SID>toggle_send_on_save()<CR>
+py connect()

doc/examples/leo_bridge_demo.leo

@@ -0,0 +1,552 b''
+<?xml version="1.0" encoding="utf-8"?>
+<?xml-stylesheet ekr_test?>
+<leo_file>
+<leo_header file_format="2" tnodes="0" max_tnode_index="0" clone_windows="0"/>
+<globals body_outline_ratio="0.307814992026">
+	<global_window_position top="257" left="131" height="627" width="1280"/>
+	<global_log_window_position top="0" left="0" height="0" width="0"/>
+</globals>
+<preferences/>
+<find_panel_settings/>
+<vnodes>
+<v t="vivainio.20080222193236" a="E"><vh>Documentation</vh>
+<v t="vivainio.20080223121915" tnodeList="vivainio.20080223121915,vivainio.20080222193236.1,vivainio.20080223133858,vivainio.20080223133922,vivainio.20080223133947,vivainio.20080223134018,vivainio.20080223134100,vivainio.20080223134118,vivainio.20080223134433,vivainio.20080223142207,vivainio.20080223134136"><vh>@nosent ILeo_doc.txt</vh>
+<v t="vivainio.20080222193236.1"><vh>Documentation</vh>
+<v t="vivainio.20080223133858"><vh>Introduction</vh></v>
+<v t="vivainio.20080223133922"><vh>Installation</vh></v>
+<v t="vivainio.20080223133947"><vh>Accessing IPython from Leo</vh></v>
+<v t="vivainio.20080223134018"><vh>Accessing Leo nodes from IPython</vh></v>
+<v t="vivainio.20080223134100"><vh>Cl definitions</vh></v>
+<v t="vivainio.20080223134118"><vh>Special node types</vh></v>
+<v t="vivainio.20080223134433"><vh>Custom push</vh></v>
+<v t="vivainio.20080223142207" a="E"><vh>Code snippets</vh></v>
+<v t="vivainio.20080223134136"><vh>Acknowledgements and history</vh></v>
+</v>
+</v>
+</v>
+<v t="vivainio.20080218184525"><vh>@chapters</vh></v>
+<v t="vivainio.20080223133721" a="E"><vh>@settings</vh>
+<v t="vivainio.20080316092617"><vh>@@string ipython_argv = ipython -pylab</vh></v>
+<v t="vivainio.20080223133721.1"><vh>@enabled-plugins</vh></v>
+</v>
+<v t="vivainio.20080218184540"><vh>@ipy-startup</vh>
+<v t="vivainio.20080218184613.1"><vh>b</vh></v>
+<v t="vivainio.20080218200031"><vh>Some classes P</vh>
+<v t="vivainio.20080218190816"><vh>File-like access</vh></v>
+<v t="vivainio.20080218200106"><vh>csv data</vh></v>
+<v t="vivainio.20080219225120"><vh>String list</vh></v>
+<v t="vivainio.20080219230342"><vh>slist to leo</vh></v>
+</v>
+</v>
+<v t="vivainio.20080218195413" a="E"><vh>Class tests</vh>
+<v t="vivainio.20080218200509"><vh>csvr</vh></v>
+<v t="vivainio.20080218191007"><vh>tempfile</vh></v>
+<v t="vivainio.20080218195413.1"><vh>rfile</vh></v>
+<v t="vivainio.20080219225804"><vh>strlist</vh></v>
+</v>
+<v t="vivainio.20080222201226" a="V"><vh>IPython script push tests</vh></v>
+<v t="vivainio.20080218201219" a="E"><vh>Direct variables</vh>
+<v t="vivainio.20080218201219.2"><vh>bar</vh></v>
+</v>
+<v t="vivainio.20080316144536" a="E"><vh>pylab tests</vh>
+<v t="vivainio.20080316145539.2"><vh>Generate testarr</vh></v>
+<v t="vivainio.20080316085925"><vh>testarr</vh></v>
+<v t="vivainio.20080316085950"><vh>Call plotter on testarr</vh></v>
+</v>
+<v t="vivainio.20080222202211"><vh>test stuff</vh></v>
+<v t="vivainio.20080223142403"><vh>@ipy-results</vh>
+<v t="vivainio.20080223142403.1"><vh>foo</vh></v>
+</v>
+<v t="vivainio.20080222202211.1" a="E"><vh>spam</vh></v>
+</vnodes>
+<tnodes>
+<t tx="vivainio.20080218184525">?</t>
+<t tx="vivainio.20080218184540">?Direct children of this node will be pushed at ipython bridge startup
+
+This node itself will *not* be pushed</t>
+<t tx="vivainio.20080218184613.1">print "world"</t>
+<t tx="vivainio.20080218190816">def rfile(body,n):
+    """ @cl rfile 
+
+    produces a StringIO (file like obj of the rest of the body) """
+
+    import StringIO
+    return StringIO.StringIO(body)
+
+def tmpfile(body,n):
+    """ @cl tmpfile
+
+    Produces a temporary file, with node body as contents
+
+    """
+    import tempfile
+    h, fname = tempfile.mkstemp()
+    f = open(fname,'w')
+    f.write(body)
+    f.close()
+    return fname
+</t>
+<t tx="vivainio.20080218191007">@cl tmpfile
+
+Hello</t>
+<t tx="vivainio.20080218195413">?</t>
+<t tx="vivainio.20080218195413.1">@cl rfile
+These
+lines
+should 
+be
+readable </t>
+<t tx="vivainio.20080218200031">@others</t>
+<t tx="vivainio.20080218200106">def csvdata(body,n):
+    import csv
+    d = csv.Sniffer().sniff(body)
+    reader = csv.reader(body.splitlines(), dialect = d)
+    return reader</t>
+<t tx="vivainio.20080218200509">@cl csvdata
+
+a,b,b
+1,2,2</t>
+<t tx="vivainio.20080218201219"></t>
+<t tx="vivainio.20080218201219.2">@cl
+"hello world"</t>
+<t tx="vivainio.20080219225120">import IPython.genutils
+def slist(body,n):
+    return IPython.genutils.SList(body.splitlines())
+</t>
+<t tx="vivainio.20080219225804">@cl slist
+hello
+world
+on
+many
+lines
+</t>
+<t tx="vivainio.20080219230342">import ipy_leo
+@ipy_leo.format_for_leo.when_type(IPython.genutils.SList)
+def format_slist(obj):
+    return "@cl slist\n" + obj.n
+</t>
+<t tx="vivainio.20080222193236">?</t>
+<t tx="vivainio.20080222193236.1">@wrap
+@nocolor</t>
+<t tx="vivainio.20080222201226"># test ipython script 'cleanup' with complex blocks
+1+2
+print "hello"
+3+4
+
+def f(x):
+    return x.upper()
+
+
+if 0:
+    print "foo"
+else:
+    print "bar"
+
+def g():
+    pass
+
+g()
+
+if 1:
+    if 1:
+        print "hello"
+
+        print "world"
+
+if 1:
+    print "hello"
+
+    print "word"
+else:
+    print "foo"
+
+    print "bar"
+    print "baz"
+
+try:
+    raise Exception
+except:
+    print "exc ok"</t>
+<t tx="vivainio.20080222202211"></t>
+<t tx="vivainio.20080222202211.1" ipython="7d71005506636f6f7264737101284b0c4bde747102732e">@cl rfile
+hello
+world
+and whatever</t>
+<t tx="vivainio.20080223121915">@others
+</t>
+<t tx="vivainio.20080223133721"></t>
+<t tx="vivainio.20080223133721.1">ipython.py</t>
+<t tx="vivainio.20080223133858">
+Introduction
+============
+
+The purpose of ILeo, or leo-ipython bridge, is being a two-way communication
+channel between Leo and IPython. The level of integration is much deeper than
+conventional integration in IDEs; most notably, you are able to store *data* in
+Leo nodes, in addition to mere program code. The possibilities of this are
+endless, and this degree of integration has not been seen previously in the python
+world.
+
+IPython users are accustomed to using things like %edit to produce non-trivial
+functions/classes (i.e. something that they don't want to enter directly on the
+interactive prompt, but creating a proper script/module involves too much
+overhead). In ILeo, this task consists just going to the Leo window, creating a node
+and writing the code there, and pressing alt+I (push-to-ipython).
+
+Obviously, you can save the Leo document as usual - this is a great advantage
+of ILeo over using %edit, you can save your experimental scripts all at one
+time, without having to organize them into script/module files (before you
+really want to, of course!)
+</t>
+<t tx="vivainio.20080223133922">
+Installation
+============
+
+You need at least Leo 4.4.7, and the development version of IPython (ILeo
+will be incorporated to IPython 0.8.3).
+
+You can get IPython from Launchpad by installing bzr and doing
+
+bzr branch lp:ipython
+
+and running "setup.py install".
+
+You need to enable the 'ipython.py' plugin in Leo: 
+
+- Help -&gt; Open LeoSettings.leo
+
+- Edit @settings--&gt;Plugins--&gt;@enabled-plugins, add/uncomment 'ipython.py'
+
+- Alternatively, you can add @settings--&gt;@enabled-plugins with body ipython.py to your leo document.
+
+- Restart Leo. Be sure that you have the console window open (start leo.py from console, or double-click leo.py on windows)
+
+- Press alt+5 OR alt-x start-ipython to launch IPython in the console that
+started leo. You can start entering IPython commands normally, and Leo will keep
+running at the same time.
+</t>
+<t tx="vivainio.20080223133947">
+Accessing IPython from Leo
+==========================
+
+IPython code
+------------
+
+Just enter IPython commands on a Leo node and press alt-I to execute
+push-to-ipython in order to execute the script in IPython. 'commands' is
+interpreted loosely here - you can enter function and class definitions, in
+addition to the things you would usually enter at IPython prompt - calculations,
+system commands etc.
+
+Everything that would be legal to enter on IPython prompt is legal to execute
+from ILeo.
+
+Results will be shows in Leo log window for convenience, in addition to the console.
+
+Suppose that a node had the following contents:
+{{{
+1+2
+print "hello"
+3+4
+
+def f(x):
+    return x.upper()
+
+f('hello world')
+}}}
+
+If you press alt+I on that node, you will see the following in Leo log window (IPython tab):
+
+{{{
+In: 1+2
+&lt;2&gt; 3
+In: 3+4
+&lt;4&gt; 7
+In: f('hello world')
+&lt;6&gt; 'HELLO WORLD'
+}}}
+
+(numbers like &lt;6&gt; mean IPython output history indices; the actual object can be
+referenced with _6 as usual in IPython).
+
+
+Plain Python code
+-----------------
+
+If the headline of the node ends with capital P, alt-I will not run the code
+through IPython translation mechanism but use the direct python 'exec' statement
+(in IPython user namespace) to execute the code. It wont be shown in IPython
+history, and sometimes it is safer (and more efficient) to execute things as
+plain Python statements. Large class definitions are good candidates for P
+nodes.
+</t>
+<t tx="vivainio.20080223134018">
+Accessing Leo nodes from IPython
+================================
+
+The real fun starts when you start entering text to leo nodes, and are using
+that as data (input/output) for your IPython work.
+
+Accessing Leo nodes happens through the variable 'wb' (short for "WorkBook")
+that exist in the IPython user namespace. Nodes that are directly accessible are
+the ones that have simple names which could also be Python variable names;
+'foo_1' will be accessible directly from IPython, whereas 'my scripts' will not.
+If you want to access a node with arbitrary headline, add a child node '@a foo'
+(@a stands for 'anchor'). Then, the parent of '@a foo' is accessible through
+'wb.foo'.
+
+You can see what nodes are accessible be entering (in IPython) wb.&lt;TAB&gt;. Example:
+
+[C:leo/src]|12&gt; wb.
+wb.b           wb.tempfile    wb.rfile       wb.NewHeadline
+wb.bar         wb.Docs        wb.strlist     wb.csvr    
+[C:leo/src]|12&gt; wb.tempfile
+           &lt;12&gt; &lt;ipy_leo.LeoNode object at 0x044B6D90&gt;
+
+So here, we meet the 'LeoNode' class that is your key to manipulating Leo
+content from IPython!
+
+LeoNode
+-------
+
+Suppose that we had a node with headline 'spam' and body: 
+
+['12',2222+32]
+
+we can access it from IPython (or from scripts entered into other Leo nodes!) by doing:
+
+C:leo/src]|19&gt; wb.spam.v
+          &lt;19&gt; ['12', 2254]
+
+'v' attribute stands for 'value', which means the node contents will be run
+through 'eval' and everything you would be able to enter into IPython prompt
+will be converted to objects. This mechanism can be extended far beyond direct
+evaluation (see '@cl definitions').
+
+'v' attribute also has a setter, i.e. you can do:
+
+wb.spam.v = "mystring"
+
+Which will result in the node 'spam' having the following text:
+
+'mystring'
+
+What assignment to 'v' does can be configured through generic functions
+('simplegeneric' module, will be explained later).
+
+Besides v, you can set the body text directly through 
+
+wb.spam.b = "some\nstring", 
+
+headline by 
+
+wb.spam.h = 'new_headline' 
+
+(obviously you must access the node through wb.new_headline from that point
+onwards), and access the contents as string list (IPython SList) through
+'wb.spam.l'.
+
+If you do 'wb.foo.v = 12' when node named 'foo' does not exist, the node titled
+'foo' will be automatically created and assigned body 12.
+
+LeoNode also supports go() that focuses the node in the Leo window, and ipush()
+that simulates pressing alt+I on the node.
+
+You can access unknownAttributes by .uA property dictionary. Unknown attributes
+allow you to store arbitrary (pickleable) python objects in the Leo nodes; the
+attributes are stored when you save the .leo document, and recreated when you
+open the document again. The attributes are not visible anywhere, but can be
+used for domain-specific metatada. Example:
+
+    [C:leo/src]|12&gt; wb.spam.uA['coords'] = (12,222)
+    [C:leo/src]|13&gt; wb.spam.uA
+               &lt;13&gt; {'coords': (12, 222)}    
+
+Accessing children with iteration and dict notation
+---------------------------------------------------
+
+Sometimes, you may want to treat a node as a 'database', where the nodes
+children represent elements in the database. You can create a new child node for
+node 'spam', with headline 'foo bar' like this:
+
+    wb.spam['foo bar'] = "Hello"
+
+And assign a new value for it by doing 
+
+    wb.spam['foo bar'].v = "Hello again"
+
+Note how you can't use .v when you first create the node - i.e. the node needs
+to be initialized by simple assignment, that will be interpreted as assignment
+to '.v'. This is a conscious design choice.
+
+If you try to do wb.spam['bar'] = 'Hello', ILeo will assign '@k bar' as the
+headline for the child instead, because 'bar' is a legal python name (and as
+such would be incorporated in the workbook namespace). This is done to avoid
+crowding the workbook namespace with extraneous items. The item will still be
+accessible as wb.spam['bar']
+
+LeoNodes are iterable, so to see the headlines of all the children of 'spam' do:
+
+    for n in wb.spam:
+        print n.h
+</t>
+<t tx="vivainio.20080223134100">
+@cl definitions
+===============
+
+If the first line in the body text is of the form '@cl sometext', IPython will
+evaluate 'sometext' and call the result with the rest of the body when you do
+'wb.foo.v'. An example is in place here. Suppose that we have defined a class (I
+use the term class in a non-python sense here)
+
+{{{
+def rfile(body,node):
+    """ @cl rfile 
+
+    produces a StringIO (file like obj) of the rest of the body """
+
+    import StringIO
+    return StringIO.StringIO(body)
+}}}
+
+(note that node is ignored here - but it could be used to access headline,
+children etc.),
+
+Now, let's say you have node 'spam' with text
+
+{{{
+@cl rfile
+hello
+world
+and whatever
+}}}
+
+Now, in IPython, we can do this:
+
+{{{    
+[C:leo/src]|22&gt; f = wb.spam.v
+[C:leo/src]|23&gt; f
+           &lt;23&gt; &lt;StringIO.StringIO instance at 0x04E7E490&gt;
+[C:leo/src]|24&gt; f.readline()
+           &lt;24&gt; u'hello\n'
+[C:leo/src]|25&gt; f.readline()
+           &lt;25&gt; u'world\n'
+[C:leo/src]|26&gt; f.readline()
+           &lt;26&gt; u'and whatever'
+[C:leo/src]|27&gt; f.readline()
+           &lt;27&gt; u''    
+}}} 
+
+You should declare new @cl types to make ILeo as convenient your problem domain
+as possible. For example, a "@cl etree" could return the elementtree object for
+xml content.
+</t>
+<t tx="vivainio.20080223134118">
+Special node types
+==================
+
+@ipy-startup
+------------
+
+If this node exist, the *direct children* of this will be pushed to IPython when
+ILeo is started (you press alt+5). Use it to push your own @cl definitions etc.
+The contents of of the node itself will be ignored.
+
+@ipy-results
+------------
+
+When you create a new node (wb.foo.v = 'stuff'), the node foo will be created as
+a child of this node. If @ipy-results does not exist, the new node will be created after the currently selected node.
+
+@a nodes
+--------
+
+You can attach these as children of existing nodes to provide a way to access
+nodes with arbitrary headlines, or to provide aliases to other nodes. If
+multiple @a nodes are attached as children of a node, all the names can be used
+to access the same object.
+</t>
+<t tx="vivainio.20080223134136">
+Acknowledgements &amp; History
+==========================
+
+This idea got started when I (Ville) saw this post by Edward Ream (the author of
+Leo) on IPython developer mailing list:
+
+    http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html
+
+I was using FreeMind as mind mapping software, and so I had an immediate use
+case for Leo (which, incidentally, is superior to FreeMind as mind mapper). The
+wheels started rolling, I got obsessed with the power of this concept
+(everything clicked together), and Edwards excitement paralleled mine.
+Everything was mind-bogglingly easy/trivial, something that is typical of all
+revolutionary technologies (think Python here).
+
+The discussion that "built" ILeo is here:
+    http://sourceforge.net/forum/forum.php?thread_id=1911662&amp;forum_id=10226    
+
+?</t>
+<t tx="vivainio.20080223134433">
+Declaring custom push-to-ipython handlers
+=========================================
+
+Sometimes, you might want to configure what alt+I on a node does. You can do
+that by creating your own push function and expose it using
+ipy_leo.expose_ileo_push(f, priority). The function should check whether the
+node should by handled by the function and raise IPython.ipapi.TryNext if it
+will not do the handling, giving the next function in the chain a chance to see
+whether it should handle the push.
+
+This example would print an uppercase version of node body if the node headline ends
+with U (yes, this is completely useless!):
+
+{{{
+def push_upcase(node):
+    if not node.h.endswith('U'):
+        raise TryNext
+    print node.b.upper()
+
+ipy_leo.expose_ileo_push(push_upcase, 12)
+}}}
+
+(the priority should be between 0-100 - typically, you don't need to care about
+it and can usually omit the argument altogether)
+</t>
+<t tx="vivainio.20080223142207">
+Example code snippets
+=====================
+
+Get list of all headlines of all the nodes in leo:
+
+    [node.h for node in wb]
+
+Create node with headline 'baz', empty body:
+    wb.baz
+
+Create 10 child nodes for baz, where i is headline and 'Hello ' + i is body:       
+
+    for i in range(10):
+        wb.baz[i] = 'Hello %d' % i
+
+
+</t>
+<t tx="vivainio.20080223142403"></t>
+<t tx="vivainio.20080223142403.1">12</t>
+<t tx="vivainio.20080316085925">array([[ 0,  1,  2],
+       [ 3,  4,  5],
+       [ 6,  7,  8],
+       [ 9, 10, 11]])</t>
+<t tx="vivainio.20080316085950"># press alt+i here to plot testarr
+
+plot(wb.testarr.v)</t>
+<t tx="vivainio.20080316092617"></t>
+<t tx="vivainio.20080316144536">Quickstart:
+    easy_install numpy    
+    easy_install matplotlib
+
+Make sure you have '@string ipython-argv = ipython -pylab' in @settings. We currently recommend using TkAgg as the backend (it's also the default)</t>
+<t tx="vivainio.20080316145539.2">#press alt+i here to generate an array for plotter
+
+wb.testarr.v = arange(12).reshape(4,3)</t>
+</tnodes>
+</leo_file>

doc/source/conf.py

@@ -0,0 +1,132 b''
+# -*- coding: utf-8 -*-
+#
+# IPython documentation build configuration file, created by
+# sphinx-quickstart.py on Sat Mar 29 15:36:13 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
+#extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'ipython'
+
+# General substitutions.
+project = 'IPython'
+copyright = '2008, Fernando Perez'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.8.3'
+# The full version, including alpha/beta/rc tags.
+release = '0.8.3'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'IPythondoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+latex_paper_size = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [('ipython','ipython.tex','IPython Documentation','Fernando Perez (and contributors)','manual')]
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

doc/source/ipython.rst

@@ -0,0 +1,5875 b''
+.. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root 'toctree' directive.
+
+IPython documentation
+=====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Introduction
+============
+
+This is the official documentation for IPython 0.x series (i.e. what
+we are used to refer to just as "IPython"). The original text of the
+manual (most of which is still in place) has been authored by Fernando
+Perez, but as recommended usage patterns and new features have
+emerged, this manual has been updated to reflect that fact. Most of
+the additions have been authored by Ville M. Vainio.
+
+The manual has been generated from reStructuredText source markup with
+Sphinx, which should make it much easier to keep it up-to-date in the
+future. Some reST artifacts and bugs may still be apparent in the
+documentation, but this should improve as the toolchain matures.
+
+Overview
+========
+
+One of Python's most useful features is its interactive interpreter.
+This system allows very fast testing of ideas without the overhead of
+creating test files as is typical in most programming languages.
+However, the interpreter supplied with the standard Python distribution
+is somewhat limited for extended interactive use.
+
+IPython is a free software project (released under the BSD license)
+which tries to:
+
+   1. Provide an interactive shell superior to Python's default. IPython
+      has many features for object introspection, system shell access,
+      and its own special command system for adding functionality when
+      working interactively. It tries to be a very efficient environment
+      both for Python code development and for exploration of problems
+      using Python objects (in situations like data analysis).
+   2. Serve as an embeddable, ready to use interpreter for your own
+      programs. IPython can be started with a single call from inside
+      another program, providing access to the current namespace. This
+      can be very useful both for debugging purposes and for situations
+      where a blend of batch-processing and interactive exploration are
+      needed.
+   3. Offer a flexible framework which can be used as the base
+      environment for other systems with Python as the underlying
+      language. Specifically scientific environments like Mathematica,
+      IDL and Matlab inspired its design, but similar ideas can be
+      useful in many fields.
+   4. Allow interactive testing of threaded graphical toolkits. IPython
+      has support for interactive, non-blocking control of GTK, Qt and
+      WX applications via special threading flags. The normal Python
+      shell can only do this for Tkinter applications.
+
+
+Main features
+-------------
+
+* Dynamic object introspection. One can access docstrings, function
+  definition prototypes, source code, source files and other details
+  of any object accessible to the interpreter with a single
+  keystroke ('?', and using '??' provides additional detail).
+* Searching through modules and namespaces with '*' wildcards, both
+  when using the '?' system and via the %psearch command.
+* Completion in the local namespace, by typing TAB at the prompt.
+  This works for keywords, modules, methods, variables and files in the
+  current directory. This is supported via the readline library, and
+  full access to configuring readline's behavior is provided. 
+  Custom completers can be implemented easily for different purposes
+  (system commands, magic arguments etc.)
+* Numbered input/output prompts with command history (persistent
+  across sessions and tied to each profile), full searching in this
+  history and caching of all input and output.
+* User-extensible 'magic' commands. A set of commands prefixed with
+  % is available for controlling IPython itself and provides
+  directory control, namespace information and many aliases to
+  common system shell commands.
+* Alias facility for defining your own system aliases.
+* Complete system shell access. Lines starting with ! are passed
+  directly to the system shell, and using !! or var = !cmd 
+  captures shell output into python variables for further use.
+* Background execution of Python commands in a separate thread.
+  IPython has an internal job manager called jobs, and a
+  conveninence backgrounding magic function called %bg.
+* The ability to expand python variables when calling the system
+  shell. In a shell command, any python variable prefixed with $ is
+  expanded. A double $$ allows passing a literal $ to the shell (for
+  access to shell and environment variables like $PATH).
+* Filesystem navigation, via a magic %cd command, along with a
+  persistent bookmark system (using %bookmark) for fast access to
+  frequently visited directories.
+* A lightweight persistence framework via the %store command, which
+  allows you to save arbitrary Python variables. These get restored
+  automatically when your session restarts.
+* Automatic indentation (optional) of code as you type (through the
+  readline library).
+* Macro system for quickly re-executing multiple lines of previous
+  input with a single name. Macros can be stored persistently via
+  %store and edited via %edit.
+* Session logging (you can then later use these logs as code in your
+  programs). Logs can optionally timestamp all input, and also store
+  session output (marked as comments, so the log remains valid
+  Python source code).
+* Session restoring: logs can be replayed to restore a previous
+  session to the state where you left it.
+* Verbose and colored exception traceback printouts. Easier to parse
+  visually, and in verbose mode they produce a lot of useful
+  debugging information (basically a terminal version of the cgitb
+  module).
+* Auto-parentheses: callable objects can be executed without
+  parentheses: 'sin 3' is automatically converted to 'sin(3)'.
+* Auto-quoting: using ',' or ';' as the first character forces
+  auto-quoting of the rest of the line: ',my_function a b' becomes
+  automatically 'my_function("a","b")', while ';my_function a b'
+  becomes 'my_function("a b")'.
+* Extensible input syntax. You can define filters that pre-process
+  user input to simplify input in special situations. This allows
+  for example pasting multi-line code fragments which start with
+  '>>>' or '...' such as those from other python sessions or the
+  standard Python documentation.
+* Flexible configuration system. It uses a configuration file which
+  allows permanent setting of all command-line options, module
+  loading, code and file execution. The system allows recursive file
+  inclusion, so you can have a base file with defaults and layers
+  which load other customizations for particular projects.
+* Embeddable. You can call IPython as a python shell inside your own
+  python programs. This can be used both for debugging code or for
+  providing interactive abilities to your programs with knowledge
+  about the local namespaces (very useful in debugging and data
+  analysis situations).
+* Easy debugger access. You can set IPython to call up an enhanced
+  version of the Python debugger (pdb) every time there is an
+  uncaught exception. This drops you inside the code which triggered
+  the exception with all the data live and it is possible to
+  navigate the stack to rapidly isolate the source of a bug. The
+  %run magic command -with the -d option- can run any script under
+  pdb's control, automatically setting initial breakpoints for you.
+  This version of pdb has IPython-specific improvements, including
+  tab-completion and traceback coloring support. For even easier
+  debugger access, try %debug after seeing an exception. winpdb is 
+  also supported, see ipy_winpdb extension.
+* Profiler support. You can run single statements (similar to
+  profile.run()) or complete programs under the profiler's control.
+  While this is possible with standard cProfile or profile modules,
+  IPython wraps this functionality with magic commands (see '%prun'
+  and '%run -p') convenient for rapid interactive work.
+* Doctest support. The special %doctest_mode command toggles a mode
+  that allows you to paste existing doctests (with leading '>>>'
+  prompts and whitespace) and uses doctest-compatible prompts and
+  output, so you can use IPython sessions as doctest code.
+
+
+Portability and Python requirements
+-----------------------------------
+
+Python requirements: IPython requires with Python version 2.3 or newer.
+If you are still using Python 2.2 and can not upgrade, the last version
+of IPython which worked with Python 2.2 was 0.6.15, so you will have to
+use that.
+
+IPython is developed under Linux, but it should work in any reasonable
+Unix-type system (tested OK under Solaris and the BSD family, for which
+a port exists thanks to Dryice Liu).
+
+Mac OS X: it works, apparently without any problems (thanks to Jim Boyle
+at Lawrence Livermore for the information). Thanks to Andrea Riciputi,
+Fink support is available.
+
+CygWin: it works mostly OK, though some users have reported problems
+with prompt coloring. No satisfactory solution to this has been found so
+far, you may want to disable colors permanently in the ipythonrc
+configuration file if you experience problems. If you have proper color
+support under cygwin, please post to the IPython mailing list so this
+issue can be resolved for all users.
+
+Windows: it works well under Windows Vista/XP/2k, and I suspect NT should
+behave similarly. Section "Installation under windows" describes
+installation details for Windows, including some additional tools needed
+on this platform.
+
+Windows 9x support is present, and has been reported to work fine (at
+least on WinME).
+
+Location
+--------
+
+IPython is generously hosted at http://ipython.scipy.org by the
+Enthought, Inc and the SciPy project. This site offers downloads,
+subversion access, mailing lists and a bug tracking system. I am very
+grateful to Enthought (http://www.enthought.com) and all of the SciPy
+team for their contribution.
+
+Installation
+============
+
+Instant instructions
+--------------------
+
+If you are of the impatient kind, under Linux/Unix simply untar/unzip
+the download, then install with 'python setup.py install'. Under
+Windows, double-click on the provided .exe binary installer.
+
+Then, take a look at Customization_ section for configuring things
+optimally and `Quick tips`_ for quick tips on efficient use of
+IPython. You can later refer to the rest of the manual for all the
+gory details.
+
+See the notes in upgrading_ section for upgrading IPython versions.
+
+
+    Detailed Unix instructions (Linux, Mac OS X, etc.)
+
+For RPM based systems, simply install the supplied package in the usual
+manner. If you download the tar archive, the process is:
+
+   1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is
+      the version number). It will make a directory called ipython-XXX.
+      Change into that directory where you will find the files README
+      and setup.py. Once you've completed the installation, you can
+      safely remove this directory.
+   2. If you are installing over a previous installation of version
+      0.2.0 or earlier, first remove your $HOME/.ipython directory,
+      since the configuration file format has changed somewhat (the '='
+      were removed from all option specifications). Or you can call
+      ipython with the -upgrade option and it will do this automatically
+      for you.
+   3. IPython uses distutils, so you can install it by simply typing at
+      the system prompt (don't type the $)::
+      
+      	$ python setup.py install
+      	
+      Note that this assumes you have root access to your machine. If
+      you don't have root access or don't want IPython to go in the
+      default python directories, you'll need to use the ``--home`` option
+      (or ``--prefix``). For example::
+      
+      	$ python setup.py install --home $HOME/local
+      	
+      will install IPython into $HOME/local and its subdirectories
+      (creating them if necessary).
+      You can type::
+      
+      	$ python setup.py --help
+      	
+      for more details.
+      
+      Note that if you change the default location for ``--home`` at
+      installation, IPython may end up installed at a location which is
+      not part of your $PYTHONPATH environment variable. In this case,
+      you'll need to configure this variable to include the actual
+      directory where the IPython/ directory ended (typically the value
+      you give to ``--home`` plus /lib/python).
+
+
+Mac OSX information
+-------------------
+
+Under OSX, there is a choice you need to make. Apple ships its own build
+of Python, which lives in the core OSX filesystem hierarchy. You can
+also manually install a separate Python, either purely by hand
+(typically in /usr/local) or by using Fink, which puts everything under
+/sw. Which route to follow is a matter of personal preference, as I've
+seen users who favor each of the approaches. Here I will simply list the
+known installation issues under OSX, along with their solutions.
+
+This page: http://geosci.uchicago.edu/~tobis/pylab.html contains
+information on this topic, with additional details on how to make
+IPython and matplotlib play nicely under OSX.
+
+To run IPython and readline on OSX "Leopard" system python, see the 
+wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard
+
+
+GUI problems
+------------
+
+The following instructions apply to an install of IPython under OSX from
+unpacking the .tar.gz distribution and installing it for the default
+Python interpreter shipped by Apple. If you are using a fink install,
+fink will take care of these details for you, by installing IPython
+against fink's Python.
+
+IPython offers various forms of support for interacting with graphical
+applications from the command line, from simple Tk apps (which are in
+principle always supported by Python) to interactive control of WX, Qt
+and GTK apps. Under OSX, however, this requires that ipython is
+installed by calling the special pythonw script at installation time,
+which takes care of coordinating things with Apple's graphical environment.
+
+So when installing under OSX, it is best to use the following command:: 
+
+	$ sudo pythonw setup.py install --install-scripts=/usr/local/bin
+
+or
+
+	$ sudo pythonw setup.py install --install-scripts=/usr/bin
+	
+depending on where you like to keep hand-installed executables.
+
+The resulting script will have an appropriate shebang line (the first
+line in the script whic begins with #!...) such that the ipython
+interpreter can interact with the OS X GUI. If the installed version
+does not work and has a shebang line that points to, for example, just
+/usr/bin/python, then you might have a stale, cached version in your
+build/scripts-<python-version> directory. Delete that directory and
+rerun the setup.py.
+
+It is also a good idea to use the special flag ``--install-scripts`` as
+indicated above, to ensure that the ipython scripts end up in a location
+which is part of your $PATH. Otherwise Apple's Python will put the
+scripts in an internal directory not available by default at the command
+line (if you use /usr/local/bin, you need to make sure this is in your
+$PATH, which may not be true by default).
+
+
+Readline problems
+-----------------
+
+By default, the Python version shipped by Apple does not include the
+readline library, so central to IPython's behavior. If you install
+IPython against Apple's Python, you will not have arrow keys, tab
+completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt
+readline library here:
+http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip
+
+If you are using OSX 10.4 (Tiger), after installing this package you
+need to either:
+
+   1. move readline.so from /Library/Python/2.3 to
+      /Library/Python/2.3/site-packages, or
+   2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip
+
+Users installing against Fink's Python or a properly hand-built one
+should not have this problem.
+
+
+DarwinPorts
+-----------
+
+I report here a message from an OSX user, who suggests an alternative
+means of using IPython under this operating system with good results.
+Please let me know of any updates that may be useful for this section.
+His message is reproduced verbatim below:
+
+    From: Markus Banfi <markus.banfi-AT-mospheira.net> 
+
+    As a MacOS X (10.4.2) user I prefer to install software using
+    DawinPorts instead of Fink. I had no problems installing ipython
+    with DarwinPorts. It's just: 
+
+    sudo port install py-ipython 
+
+    It automatically resolved all dependencies (python24, readline,
+    py-readline). So far I did not encounter any problems with the
+    DarwinPorts port of ipython. 
+
+
+
+Windows instructions
+--------------------
+
+Some of IPython's very useful features are:
+
+    * Integrated readline support (Tab-based file, object and attribute
+      completion, input history across sessions, editable command line,
+      etc.)
+    * Coloring of prompts, code and tracebacks.
+
+.. _pyreadline:
+
+These, by default, are only available under Unix-like operating systems.
+However, thanks to Gary Bishop's work, Windows XP/2k users can also
+benefit from them. His readline library originally implemented both GNU
+readline functionality and color support, so that IPython under Windows
+XP/2k can be as friendly and powerful as under Unix-like environments.
+
+This library, now named PyReadline, has been absorbed by the IPython
+team (Jörgen Stenarson, in particular), and it continues to be developed
+with new features, as well as being distributed directly from the
+IPython site.
+
+The PyReadline extension requires CTypes and the windows IPython
+installer needs PyWin32, so in all you need:
+
+   1. PyWin32 from http://sourceforge.net/projects/pywin32.
+   2. PyReadline for Windows from
+      http://ipython.scipy.org/moin/PyReadline/Intro. That page contains
+      further details on using and configuring the system to your liking.
+   3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes
+      from http://starship.python.net/crew/theller/ctypes(you must use
+      version 0.9.1 or newer). This package is included in Python 2.5,
+      so you don't need to manually get it if your Python version is 2.5
+      or newer.
+
+Warning about a broken readline-like library: several users have
+reported problems stemming from using the pseudo-readline library at
+http://newcenturycomputers.net/projects/readline.html. This is a broken
+library which, while called readline, only implements an incomplete
+subset of the readline API. Since it is still called readline, it fools
+IPython's detection mechanisms and causes unpredictable crashes later.
+If you wish to use IPython under Windows, you must NOT use this library,
+which for all purposes is (at least as of version 1.6) terminally broken.
+
+
+Installation procedure
+----------------------
+
+Once you have the above installed, from the IPython download directory
+grab the ipython-XXX.win32.exe file, where XXX represents the version
+number. This is a regular windows executable installer, which you can
+simply double-click to install. It will add an entry for IPython to your
+Start Menu, as well as registering IPython in the Windows list of
+applications, so you can later uninstall it from the Control Panel.
+
+IPython tries to install the configuration information in a directory
+named .ipython (_ipython under Windows) located in your 'home'
+directory. IPython sets this directory by looking for a HOME environment
+variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH
+(these are always defined by Windows). This typically gives something
+like C:\Documents and Settings\YourUserName, but your local details may
+vary. In this directory you will find all the files that configure
+IPython's defaults, and you can put there your profiles and extensions.
+This directory is automatically added by IPython to sys.path, so
+anything you place there can be found by import statements.
+
+
+Upgrading
+---------
+
+For an IPython upgrade, you should first uninstall the previous version.
+This will ensure that all files and directories (such as the
+documentation) which carry embedded version strings in their names are
+properly removed.
+
+
+Manual installation under Win32
+-------------------------------
+
+In case the automatic installer does not work for some reason, you can
+download the ipython-XXX.tar.gz file, which contains the full IPython
+source distribution (the popular WinZip can read .tar.gz files). After
+uncompressing the archive, you can install it at a command terminal just
+like any other Python module, by using 'python setup.py install'.
+
+After the installation, run the supplied win32_manual_post_install.py
+script, which creates the necessary Start Menu shortcuts for you.
+
+
+.. upgrading:
+
+Upgrading from a previous version
+---------------------------------
+
+If you are upgrading from a previous version of IPython, you may want
+to upgrade the contents of your ~/.ipython directory. Just run
+%upgrade, look at the diffs and delete the suggested files manually,
+if you think you can lose the old versions. %upgrade will never
+overwrite or delete anything.
+
+Initial configuration of your environment
+=========================================
+
+This section will help you set various things in your environment for
+your IPython sessions to be as efficient as possible. All of IPython's
+configuration information, along with several example files, is stored
+in a directory named by default $HOME/.ipython. You can change this by
+defining the environment variable IPYTHONDIR, or at runtime with the
+command line option -ipythondir.
+
+If all goes well, the first time you run IPython it should
+automatically create a user copy of the config directory for you,
+based on its builtin defaults. You can look at the files it creates to
+learn more about configuring the system. The main file you will modify
+to configure IPython's behavior is called ipythonrc (with a .ini
+extension under Windows), included for reference in `ipythonrc`_ 
+section. This file is very commented and has many variables you can
+change to suit your taste, you can find more details in
+Sec. customization_. Here we discuss the basic things you will want to
+make sure things are working properly from the beginning.
+
+
+.. _Accessing help:
+
+Access to the Python help system
+--------------------------------
+
+This is true for Python in general (not just for IPython): you should
+have an environment variable called PYTHONDOCS pointing to the directory
+where your HTML Python documentation lives. In my system it's
+/usr/share/doc/python-docs-2.3.4/html, check your local details or ask
+your systems administrator.
+
+This is the directory which holds the HTML version of the Python
+manuals. Unfortunately it seems that different Linux distributions
+package these files differently, so you may have to look around a bit.
+Below I show the contents of this directory on my system for reference::
+
+    [html]> ls 
+    about.dat acks.html dist/ ext/ index.html lib/ modindex.html
+    stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
+
+You should really make sure this variable is correctly set so that
+Python's pydoc-based help system works. It is a powerful and convenient
+system with full access to the Python manuals and all modules accessible
+to you.
+
+Under Windows it seems that pydoc finds the documentation automatically,
+so no extra setup appears necessary.
+
+
+Editor
+------
+
+The %edit command (and its alias %ed) will invoke the editor set in your
+environment as EDITOR. If this variable is not set, it will default to
+vi under Linux/Unix and to notepad under Windows. You may want to set
+this variable properly and to a lightweight editor which doesn't take
+too long to start (that is, something other than a new instance of
+Emacs). This way you can edit multi-line code quickly and with the power
+of a real editor right inside IPython.
+
+If you are a dedicated Emacs user, you should set up the Emacs server so
+that new requests are handled by the original process. This means that
+almost no time is spent in handling the request (assuming an Emacs
+process is already running). For this to work, you need to set your
+EDITOR environment variable to 'emacsclient'. The code below, supplied
+by Francois Pinard, can then be used in your .emacs file to enable the
+server::
+
+    (defvar server-buffer-clients) 
+    (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) 
+      (server-start) 
+      (defun fp-kill-server-with-buffer-routine () 
+        (and server-buffer-clients (server-done))) 
+      (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
+
+You can also set the value of this editor via the commmand-line option
+'-editor' or in your ipythonrc file. This is useful if you wish to use
+specifically for IPython an editor different from your typical default
+(and for Windows users who tend to use fewer environment variables).
+
+
+Color
+-----
+
+The default IPython configuration has most bells and whistles turned on
+(they're pretty safe). But there's one that may cause problems on some
+systems: the use of color on screen for displaying information. This is
+very useful, since IPython can show prompts and exception tracebacks
+with various colors, display syntax-highlighted source code, and in
+general make it easier to visually parse information.
+
+The following terminals seem to handle the color sequences fine:
+
+    * Linux main text console, KDE Konsole, Gnome Terminal, E-term,
+      rxvt, xterm.
+    * CDE terminal (tested under Solaris). This one boldfaces light colors.
+    * (X)Emacs buffers. See the emacs_ section for more details on
+      using IPython with (X)Emacs.
+    * A Windows (XP/2k) command prompt with pyreadline_.
+    * A Windows (XP/2k) CygWin shell. Although some users have reported
+      problems; it is not clear whether there is an issue for everyone
+      or only under specific configurations. If you have full color
+      support under cygwin, please post to the IPython mailing list so
+      this issue can be resolved for all users.
+
+These have shown problems:
+
+    * Windows command prompt in WinXP/2k logged into a Linux machine via
+      telnet or ssh.
+    * Windows native command prompt in WinXP/2k, without Gary Bishop's
+      extensions. Once Gary's readline library is installed, the normal
+      WinXP/2k command prompt works perfectly.
+
+Currently the following color schemes are available:
+
+    * NoColor: uses no color escapes at all (all escapes are empty '' ''
+      strings). This 'scheme' is thus fully safe to use in any terminal.
+    * Linux: works well in Linux console type environments: dark
+      background with light fonts. It uses bright colors for
+      information, so it is difficult to read if you have a light
+      colored background.
+    * LightBG: the basic colors are similar to those in the Linux scheme
+      but darker. It is easy to read in terminals with light backgrounds.
+
+IPython uses colors for two main groups of things: prompts and
+tracebacks which are directly printed to the terminal, and the object
+introspection system which passes large sets of data through a pager.
+
+
+Input/Output prompts and exception tracebacks
+---------------------------------------------
+
+You can test whether the colored prompts and tracebacks work on your
+system interactively by typing '%colors Linux' at the prompt (use
+'%colors LightBG' if your terminal has a light background). If the input
+prompt shows garbage like::
+
+    [0;32mIn [[1;32m1[0;32m]: [0;00m
+                               
+instead of (in color) something like::
+    
+    In [1]:
+        
+this means that your terminal doesn't properly handle color escape
+sequences. You can go to a 'no color' mode by typing '%colors NoColor'.
+
+You can try using a different terminal emulator program (Emacs users,
+see below). To permanently set your color preferences, edit the file
+$HOME/.ipython/ipythonrc and set the colors option to the desired value.
+
+
+Object details (types, docstrings, source code, etc.)
+-----------------------------------------------------
+
+IPython has a set of special functions for studying the objects you
+are working with, discussed in detail in Sec. `dynamic object
+information`_. But this system relies on passing information which is
+longer than your screen through a data pager, such as the common Unix
+less and more programs. In order to be able to see this information in
+color, your pager needs to be properly configured. I strongly
+recommend using less instead of more, as it seems that more simply can
+not understand colored text correctly.
+
+In order to configure less as your default pager, do the following:
+
+   1. Set the environment PAGER variable to less.
+   2. Set the environment LESS variable to -r (plus any other options
+      you always want to pass to less by default). This tells less to
+      properly interpret control sequences, which is how color
+      information is given to your terminal.
+
+For the csh or tcsh shells, add to your ~/.cshrc file the lines::
+
+    setenv PAGER less 
+    setenv LESS -r
+
+There is similar syntax for other Unix shells, look at your system
+documentation for details.
+
+If you are on a system which lacks proper data pagers (such as Windows),
+IPython will use a very limited builtin pager.
+
+.. _emacs:
+
+(X)Emacs configuration
+----------------------
+
+Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
+currently (X)Emacs and IPython get along very well.
+
+Important note: You will need to use a recent enough version of
+python-mode.el, along with the file ipython.el. You can check that the
+version you have of python-mode.el is new enough by either looking at
+the revision number in the file itself, or asking for it in (X)Emacs via
+M-x py-version. Versions 4.68 and newer contain the necessary fixes for
+proper IPython support.
+
+The file ipython.el is included with the IPython distribution, in the
+documentation directory (where this manual resides in PDF and HTML
+formats).
+
+Once you put these files in your Emacs path, all you need in your .emacs
+file is::
+
+    (require 'ipython) 
+
+This should give you full support for executing code snippets via
+IPython, opening IPython as your Python shell via C-c !, etc.
+
+If you happen to get garbage instead of colored prompts as described in
+the previous section, you may need to set also in your .emacs file::
+
+    (setq ansi-color-for-comint-mode t) 
+
+
+Notes:
+
+    * There is one caveat you should be aware of: you must start the
+      IPython shell before attempting to execute any code regions via
+      ``C-c |``. Simply type C-c ! to start IPython before passing any code
+      regions to the interpreter, and you shouldn't experience any
+      problems.
+      This is due to a bug in Python itself, which has been fixed for
+      Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [
+      737947 ]).
+    * The (X)Emacs support is maintained by Alexander Schmolck, so all
+      comments/requests should be directed to him through the IPython
+      mailing lists.
+    * This code is still somewhat experimental so it's a bit rough
+      around the edges (although in practice, it works quite well).
+    * Be aware that if you customize py-python-command previously, this
+      value will override what ipython.el does (because loading the
+      customization variables comes later).
+
+.. Quick tips:
+
+Quick tips
+==========
+
+IPython can be used as an improved replacement for the Python prompt,
+and for that you don't really need to read any more of this manual. But
+in this section we'll try to summarize a few tips on how to make the
+most effective use of it for everyday Python development, highlighting
+things you might miss in the rest of the manual (which is getting long).
+We'll give references to parts in the manual which provide more detail
+when appropriate.
+
+The following article by Jeremy Jones provides an introductory tutorial
+about IPython:
+http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
+
+    * The TAB key. TAB-completion, especially for attributes, is a
+      convenient way to explore the structure of any object you're
+      dealing with. Simply type object_name.<TAB> and a list of the
+      object's attributes will be printed (see readline_ for
+      more). Tab completion also works on
+      file and directory names, which combined with IPython's alias
+      system allows you to do from within IPython many of the things you
+      normally would need the system shell for.
+    * Explore your objects. Typing object_name? will print all sorts of
+      details about any object, including docstrings, function
+      definition lines (for call arguments) and constructor details for
+      classes. The magic commands %pdoc, %pdef, %psource and %pfile will
+      respectively print the docstring, function definition line, full
+      source code and the complete file for any object (when they can be
+      found). If automagic is on (it is by default), you don't need to
+      type the '%' explicitly. See sec. `dynamic object information`_
+      for more.
+    * The %run magic command allows you to run any python script and
+      load all of its data directly into the interactive namespace.
+      Since the file is re-read from disk each time, changes you make to
+      it are reflected immediately (in contrast to the behavior of
+      import). I rarely use import for code I am testing, relying on
+      %run instead. See magic_ section for more on this
+      and other magic commands, or type the name of any magic command
+      and ? to get details on it. See also sec. dreload_ for a
+      recursive reload command.
+      %run also has special flags for timing the execution of your
+      scripts (-t) and for executing them under the control of either
+      Python's pdb debugger (-d) or profiler (-p). With all of these,
+      %run can be used as the main tool for efficient interactive
+      development of code which you write in your editor of choice.
+    * Use the Python debugger, pdb. The %pdb
+      command allows you to toggle on and off the automatic invocation
+      of an IPython-enhanced pdb debugger (with coloring, tab completion
+      and more) at any uncaught exception. The advantage of this is that
+      pdb starts inside the function where the exception occurred, with
+      all data still available. You can print variables, see code,
+      execute statements and even walk up and down the call stack to
+      track down the true source of the problem (which often is many
+      layers in the stack above where the exception gets triggered).
+      Running programs with %run and pdb active can be an efficient to
+      develop and debug code, in many cases eliminating the need for
+      print statements or external debugging tools. I often simply put a
+      1/0 in a place where I want to take a look so that pdb gets
+      called, quickly view whatever variables I need to or test various
+      pieces of code and then remove the 1/0.
+      Note also that '%run -d' activates pdb and automatically sets
+      initial breakpoints for you to step through your code, watch
+      variables, etc. See Sec. `Output caching`_ for
+      details.
+    * Use the output cache. All output results are automatically stored
+      in a global dictionary named Out and variables named _1, _2, etc.
+      alias them. For example, the result of input line 4 is available
+      either as Out[4] or as _4. Additionally, three variables named _,
+      __ and ___ are always kept updated with the for the last three
+      results. This allows you to recall any previous result and further
+      use it for new calculations. See Sec. `Output caching`_ for more.
+    * Put a ';' at the end of a line to supress the printing of output.
+      This is useful when doing calculations which generate long output
+      you are not interested in seeing. The _* variables and the Out[]
+      list do get updated with the contents of the output, even if it is
+      not printed. You can thus still access the generated results this
+      way for further processing.
+    * A similar system exists for caching input. All input is stored in
+      a global list called In , so you can re-execute lines 22 through
+      28 plus line 34 by typing 'exec In[22:29]+In[34]' (using Python
+      slicing notation). If you need to execute the same set of lines
+      often, you can assign them to a macro with the %macro function.
+      See sec. `Input caching`_ for more.
+    * Use your input history. The %hist command can show you all
+      previous input, without line numbers if desired (option -n) so you
+      can directly copy and paste code either back in IPython or in a
+      text editor. You can also save all your history by turning on
+      logging via %logstart; these logs can later be either reloaded as
+      IPython sessions or used as code for your programs.
+    * Define your own system aliases. Even though IPython gives you
+      access to your system shell via the ! prefix, it is convenient to
+      have aliases to the system commands you use most often. This
+      allows you to work seamlessly from inside IPython with the same
+      commands you are used to in your system shell.
+      IPython comes with some pre-defined aliases and a complete system
+      for changing directories, both via a stack (see %pushd, %popd and
+      %dhist) and via direct %cd. The latter keeps a history of visited
+      directories and allows you to go to any previously visited one.
+    * Use Python to manipulate the results of system commands. The '!!'
+      special syntax, and the %sc and %sx magic commands allow you to
+      capture system output into Python variables.
+    * Expand python variables when calling the shell (either via '!' and
+      '!!' or via aliases) by prepending a $ in front of them. You can
+      also expand complete python expressions. See 
+      `System shell access`_ for more.
+    * Use profiles to maintain different configurations (modules to
+      load, function definitions, option settings) for particular tasks.
+      You can then have customized versions of IPython for specific
+      purposes. See sec. profiles_ for more.
+    * Embed IPython in your programs. A few lines of code are enough to
+      load a complete IPython inside your own programs, giving you the
+      ability to work with your data interactively after automatic
+      processing has been completed. See sec. embedding_
+      for more.
+    * Use the Python profiler. When dealing with performance issues, the
+      %run command with a -p option allows you to run complete programs
+      under the control of the Python profiler. The %prun command does a
+      similar job for single Python expressions (like function calls).
+    * Use the IPython.demo.Demo class to load any Python script as an
+      interactive demo. With a minimal amount of simple markup, you can
+      control the execution of the script, stopping as needed. See
+      sec. `interactive demos`_ for more.
+    * Run your doctests from within IPython for development and
+      debugging. The special %doctest_mode command toggles a mode where
+      the prompt, output and exceptions display matches as closely as
+      possible that of the default Python interpreter. In addition, this
+      mode allows you to directly paste in code that contains leading
+      '>>>' prompts, even if they have extra leading whitespace (as is
+      common in doctest files). This combined with the '%history -tn'
+      call to see your translated history (with these extra prompts
+      removed and no line numbers) allows for an easy doctest workflow,
+      where you can go from doctest to interactive execution to pasting
+      into valid Python code as needed.
+
+
+Source code handling tips
+-------------------------
+
+IPython is a line-oriented program, without full control of the
+terminal. Therefore, it doesn't support true multiline editing. However,
+it has a number of useful tools to help you in dealing effectively with
+more complex editing.
+
+The %edit command gives a reasonable approximation of multiline editing,
+by invoking your favorite editor on the spot. IPython will execute the
+code you type in there as if it were typed interactively. Type %edit?
+for the full details on the edit command.
+
+If you have typed various commands during a session, which you'd like to
+reuse, IPython provides you with a number of tools. Start by using %hist
+to see your input history, so you can see the line numbers of all input.
+Let us say that you'd like to reuse lines 10 through 20, plus lines 24
+and 28. All the commands below can operate on these with the syntax::
+
+    %command 10-20 24 28 
+
+where the command given can be:
+
+    * %macro <macroname>: this stores the lines into a variable which,
+      when called at the prompt, re-executes the input. Macros can be
+      edited later using '%edit macroname', and they can be stored
+      persistently across sessions with '%store macroname' (the storage
+      system is per-profile). The combination of quick macros,
+      persistent storage and editing, allows you to easily refine
+      quick-and-dirty interactive input into permanent utilities, always
+      available both in IPython and as files for general reuse.
+    * %edit: this will open a text editor with those lines pre-loaded
+      for further modification. It will then execute the resulting
+      file's contents as if you had typed it at the prompt.
+    * %save <filename>: this saves the lines directly to a named file on
+      disk.
+
+While %macro saves input lines into memory for interactive re-execution,
+sometimes you'd like to save your input directly to a file. The %save
+magic does this: its input sytnax is the same as %macro, but it saves
+your input directly to a Python file. Note that the %logstart command
+also saves input, but it logs all input to disk (though you can
+temporarily suspend it and reactivate it with %logoff/%logon); %save
+allows you to select which lines of input you need to save.
+
+
+Lightweight 'version control'
+-----------------------------
+
+When you call %edit with no arguments, IPython opens an empty editor
+with a temporary file, and it returns the contents of your editing
+session as a string variable. Thanks to IPython's output caching
+mechanism, this is automatically stored::
+
+    In [1]: %edit
+
+    IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
+
+    Editing... done. Executing edited code...
+
+    hello - this is a temporary file
+
+    Out[1]: "print 'hello - this is a temporary file'\n"
+
+Now, if you call '%edit -p', IPython tries to open an editor with the
+same data as the last time you used %edit. So if you haven't used %edit
+in the meantime, this same contents will reopen; however, it will be
+done in a new file. This means that if you make changes and you later
+want to find an old version, you can always retrieve it by using its
+output number, via '%edit _NN', where NN is the number of the output
+prompt.
+
+Continuing with the example above, this should illustrate this idea::
+
+    In [2]: edit -p
+
+    IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
+
+    Editing... done. Executing edited code...
+
+    hello - now I made some changes
+
+    Out[2]: "print 'hello - now I made some changes'\n"
+
+    In [3]: edit _1
+
+    IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
+
+    Editing... done. Executing edited code...
+
+    hello - this is a temporary file
+
+    IPython version control at work :)
+
+    Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
+
+
+This section was written after a contribution by Alexander Belchenko on
+the IPython user list.
+
+
+Effective logging
+-----------------
+
+A very useful suggestion sent in by Robert Kern follows:
+
+I recently happened on a nifty way to keep tidy per-project log files. I
+made a profile for my project (which is called "parkfield").
+
+    include ipythonrc
+
+    # cancel earlier logfile invocation:
+
+    logfile ''
+
+    execute import time
+
+    execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
+
+    execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
+
+I also added a shell alias for convenience:
+
+    alias parkfield="ipython -pylab -profile parkfield" 
+
+Now I have a nice little directory with everything I ever type in,
+organized by project and date.
+
+Contribute your own: If you have your own favorite tip on using IPython
+efficiently for a certain task (especially things which can't be done in
+the normal Python interpreter), don't hesitate to send it!
+
+.. _Command line options:
+
+Command-line use
+================
+
+You start IPython with the command::
+
+    $ ipython [options] files
+
+If invoked with no options, it executes all the files listed in sequence
+and drops you into the interpreter while still acknowledging any options
+you may have set in your ipythonrc file. This behavior is different from
+standard Python, which when called as python -i will only execute one
+file and ignore your configuration setup.
+
+Please note that some of the configuration options are not available at
+the command line, simply because they are not practical here. Look into
+your ipythonrc configuration file for details on those. This file
+typically installed in the $HOME/.ipython directory. For Windows users,
+$HOME resolves to C:\\Documents and Settings\\YourUserName in most
+instances. In the rest of this text, we will refer to this directory as
+IPYTHONDIR.
+
+.. _Threading options:
+
+
+Special Threading Options
+-------------------------
+
+The following special options are ONLY valid at the beginning of the
+command line, and not later. This is because they control the initial-
+ization of ipython itself, before the normal option-handling mechanism
+is active.
+
+    -gthread, -qthread, -q4thread, -wthread, -pylab: 
+	Only one of these can be given, and it can only be given as
+	the first option passed to IPython (it will have no effect in
+	any other position).  They provide threading support for the
+	GTK, Qt (versions 3 and 4) and WXPython toolkits, and for the
+	matplotlib library.
+
+	With any of the first four options, IPython starts running a
+	separate thread for the graphical toolkit's operation, so that
+	you can open and control graphical elements from within an
+	IPython command line, without blocking. All four provide
+	essentially the same functionality, respectively for GTK, Qt3,
+	Qt4 and WXWidgets (via their Python interfaces).
+
+	Note that with -wthread, you can additionally use the
+	-wxversion option to request a specific version of wx to be
+	used.  This requires that you have the wxversion Python module
+	installed, which is part of recent wxPython distributions.
+
+	If -pylab is given, IPython loads special support for the mat
+	plotlib library (http://matplotlib.sourceforge.net), allowing
+	interactive usage of any of its backends as defined in the
+	user's ~/.matplotlib/matplotlibrc file. It automatically
+	activates GTK, Qt or WX threading for IPyhton if the choice of
+	matplotlib backend requires it. It also modifies the %run
+	command to correctly execute (without blocking) any
+	matplotlib-based script which calls show() at the end.
+
+    -tk
+	The -g/q/q4/wthread options, and -pylab (if matplotlib is
+	configured to use GTK, Qt3, Qt4 or WX), will normally block Tk
+	graphical interfaces. This means that when either GTK, Qt or WX
+	threading is active, any attempt to open a Tk GUI will result in a
+	dead window, and possibly cause the Python interpreter to crash.
+	An extra option, -tk, is available to address this issue. It can
+	only be given as a second option after any of the above (-gthread,
+	-wthread or -pylab).
+
+	If -tk is given, IPython will try to coordinate Tk threading
+	with GTK, Qt or WX. This is however potentially unreliable, and
+	you will have to test on your platform and Python configuration to
+	determine whether it works for you. Debian users have reported
+	success, apparently due to the fact that Debian builds all of Tcl,
+	Tk, Tkinter and Python with pthreads support. Under other Linux
+	environments (such as Fedora Core 2/3), this option has caused
+	random crashes and lockups of the Python interpreter. Under other
+	operating systems (Mac OSX and Windows), you'll need to try it to
+	find out, since currently no user reports are available.
+    
+	There is unfortunately no way for IPython to determine at run time
+	whether -tk will work reliably or not, so you will need to do some
+	experiments before relying on it for regular work.
+
+
+
+Regular Options
+---------------
+
+After the above threading options have been given, regular options can
+follow in any order. All options can be abbreviated to their shortest
+non-ambiguous form and are case-sensitive. One or two dashes can be
+used. Some options have an alternate short form, indicated after a ``|``.
+
+Most options can also be set from your ipythonrc configuration file. See
+the provided example for more details on what the options do. Options
+given at the command line override the values set in the ipythonrc file.
+
+All options with a [no] prepended can be specified in negated form
+(-nooption instead of -option) to turn the feature off.
+
+    -help  print a help message and exit.
+
+    -pylab
+	this can only be given as the first option passed to IPython
+	(it will have no effect in any other position). It adds
+	special support for the matplotlib library
+	(http://matplotlib.sourceforge.ne), allowing interactive usage
+	of any of its backends as defined in the user's .matplotlibrc
+	file.  It automatically activates GTK or WX threading for
+	IPyhton if the choice of matplotlib backend requires it. It
+	also modifies the %run command to correctly execute (without
+	blocking) any matplotlib-based script which calls show() at
+	the end. See `Matplotlib support`_ for more details.
+
+    -autocall <val>
+	Make IPython automatically call any callable object even if you
+	didn't type explicit parentheses. For example, 'str 43' becomes
+	'str(43)' automatically. The value can be '0' to disable the feature,
+	'1' for smart autocall, where it is not applied if there are no more
+	arguments on the line, and '2' for full autocall, where all callable
+	objects are automatically called (even if no arguments are
+	present). The default is '1'.
+
+    -[no]autoindent    
+	Turn automatic indentation on/off.
+
+    -[no]automagic 
+	make magic commands automatic (without needing their first character
+	to be %). Type %magic at the IPython prompt for more information.
+
+    -[no]autoedit_syntax 
+	When a syntax error occurs after editing a file, automatically
+	open the file to the trouble causing line for convenient
+	fixing.
+
+    -[no]banner		Print the initial information banner (default on).
+
+    -c <command>
+	execute the given command string. This is similar to the -c
+	option in the normal Python interpreter.
+
+    -cache_size, cs <n> 
+	size of the output cache (maximum number of entries to hold in
+	memory). The default is 1000, you can change it permanently in your
+	config file. Setting it to 0 completely disables the caching system,
+	and the minimum value accepted is 20 (if you provide a value less than
+	20, it is reset to 0 and a warning is issued) This limit is defined
+	because otherwise you'll spend more time re-flushing a too small cache
+	than working.
+
+    -classic, cl 
+	Gives IPython a similar feel to the classic Python
+	prompt.
+
+    -colors <scheme> 
+	Color scheme for prompts and exception reporting. Currently
+	implemented: NoColor, Linux and LightBG.
+
+    -[no]color_info 
+	IPython can display information about objects via a set of functions,
+	and optionally can use colors for this, syntax highlighting source
+	code and various other elements.  However, because this information is
+	passed through a pager (like 'less') and many pagers get confused with
+	color codes, this option is off by default. You can test it and turn
+	it on permanently in your ipythonrc file if it works for you. As a
+	reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
+	that in RedHat 7.2 doesn't.
+
+	Test it and turn it on permanently if it works with your
+	system. The magic function %color_info allows you to toggle this
+	interactively for testing.
+
+    -[no]debug 
+	Show information about the loading process. Very useful to pin down
+	problems with your configuration files or to get details about
+	session restores.
+
+    -[no]deep_reload: 
+	IPython can use the deep_reload module which reloads changes in
+	modules recursively (it replaces the reload() function, so you don't
+	need to change anything to use it).  deep_reload() forces a full
+	reload of modules whose code may have changed, which the default
+	reload() function does not.
+
+	When deep_reload is off, IPython will use the normal reload(),
+	but deep_reload will still be available as dreload(). This
+	feature is off by default [which means that you have both
+	normal reload() and dreload()].
+
+    -editor <name>
+	Which editor to use with the %edit command. By default,
+	IPython will honor your EDITOR environment variable (if not
+	set, vi is the Unix default and notepad the Windows one).
+	Since this editor is invoked on the fly by IPython and is
+	meant for editing small code snippets, you may want to use a
+	small, lightweight editor here (in case your default EDITOR is
+	something like Emacs).
+
+    -ipythondir <name> 
+	name of your IPython configuration directory IPYTHONDIR. This
+	can also be specified through the environment variable
+	IPYTHONDIR.
+
+    -log, l 
+	generate a log file of all input. The file is named
+	ipython_log.py in your current directory (which prevents logs
+	from multiple IPython sessions from trampling each other). You
+	can use this to later restore a session by loading your
+	logfile as a file to be executed with option -logplay (see
+	below).
+
+    -logfile, lf <name>   specify the name of your logfile.
+
+    -logplay, lp <name> 
+
+      you can replay a previous log. For restoring a session as close as
+      possible to the state you left it in, use this option (don't just run
+      the logfile). With -logplay, IPython will try to reconstruct the
+      previous working environment in full, not just execute the commands in
+      the logfile.
+
+      When a session is restored, logging is automatically turned on
+      again with the name of the logfile it was invoked with (it is
+      read from the log header). So once you've turned logging on for
+      a session, you can quit IPython and reload it as many times as
+      you want and it will continue to log its history and restore
+      from the beginning every time.
+      
+      Caveats: there are limitations in this option. The history
+      variables _i*,_* and _dh don't get restored properly. In the
+      future we will try to implement full session saving by writing
+      and retrieving a 'snapshot' of the memory state of IPython. But
+      our first attempts failed because of inherent limitations of
+      Python's Pickle module, so this may have to wait.
+
+    -[no]messages   
+	Print messages which IPython collects about its startup
+	process (default on).
+
+    -[no]pdb
+	Automatically call the pdb debugger after every uncaught
+	exception. If you are used to debugging using pdb, this puts
+	you automatically inside of it after any call (either in
+	IPython or in code called by it) which triggers an exception
+	which goes uncaught.
+
+    -[no]pprint
+	ipython can optionally use the pprint (pretty printer) module
+	for displaying results. pprint tends to give a nicer display
+	of nested data structures. If you like it, you can turn it on
+	permanently in your config file (default off).
+
+    -profile, p <name>
+
+	assume that your config file is ipythonrc-<name> or
+	ipy_profile_<name>.py (looks in current dir first, then in
+	IPYTHONDIR).  This is a quick way to keep and load multiple
+	config files for different tasks, especially if you use the
+	include option of config files. You can keep a basic
+	IPYTHONDIR/ipythonrc file and then have other 'profiles' which
+	include this one and load extra things for particular
+	tasks. For example:
+
+	1. $HOME/.ipython/ipythonrc : load basic things you always want.
+	2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
+	3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
+
+	Since it is possible to create an endless loop by having
+	circular file inclusions, IPython will stop if it reaches 15
+	recursive inclusions.
+
+    -prompt_in1, pi1 <string>
+	Specify the string used for input prompts. Note that if you
+	are using numbered prompts, the number is represented with a
+	'\#' in the string. Don't forget to quote strings with spaces
+	embedded in them. Default: 'In [\#]:'.  Sec. Prompts_
+	discusses in detail all the available escapes to customize
+	your prompts.
+
+    -prompt_in2, pi2 <string>
+	Similar to the previous option, but used for the continuation
+	prompts. The special sequence '\D' is similar to '\#', but
+	with all digits replaced dots (so you can have your
+	continuation prompt aligned with your input prompt).  Default:
+	' .\D.:' (note three spaces at the start for alignment with
+	'In [\#]').
+
+    -prompt_out,po <string> 
+	String used for output prompts, also uses numbers like
+	prompt_in1. Default: 'Out[\#]:'
+
+    -quick   start in bare bones mode (no config file loaded).
+
+    -rcfile <name>   
+	name of your IPython resource configuration file. Normally
+	IPython loads ipythonrc (from current directory) or
+	IPYTHONDIR/ipythonrc.
+
+	If the loading of your config file fails, IPython starts with
+	a bare bones configuration (no modules loaded at all).
+
+    -[no]readline
+	use the readline library, which is needed to support name
+	completion and command history, among other things.  It is
+	enabled by default, but may cause problems for users of
+	X/Emacs in Python comint or shell buffers.
+
+	Note that X/Emacs 'eterm' buffers (opened with M-x term) support
+	IPython's readline and syntax coloring fine, only 'emacs' (M-x
+	shell and C-c !) buffers do not.
+
+    -screen_length, sl <n>
+	number of lines of your screen. This is used to control
+	printing of very long strings. Strings longer than this number
+	of lines will be sent through a pager instead of directly
+	printed.
+
+	The default value for this is 0, which means IPython will
+	auto-detect your screen size every time it needs to print certain
+	potentially long strings (this doesn't change the behavior of the
+	'print' keyword, it's only triggered internally). If for some
+	reason this isn't working well (it needs curses support), specify
+	it yourself. Otherwise don't change the default.
+
+    -separate_in, si <string>
+
+	separator before input prompts.
+	Default: '\n'
+
+    -separate_out, so <string>  
+        separator before output prompts.
+        Default: nothing.
+
+    -separate_out2, so2
+	separator after output prompts.
+	Default: nothing.
+	For these three options, use the value 0 to specify no separator.
+
+    -nosep   
+	shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
+	0'. Simply removes all input/output separators.
+
+    -upgrade 
+	allows you to upgrade your IPYTHONDIR configuration when you
+	install a new version of IPython. Since new versions may
+	include new command line options or example files, this copies
+	updated ipythonrc-type files. However, it backs up (with a
+	.old extension) all files which it overwrites so that you can
+	merge back any customizations you might have in your personal
+	files. Note that you should probably use %upgrade instead,
+	it's a safer alternative.
+
+
+    -Version    print version information and exit.
+
+    -wxversion <string> 
+	Select a specific version of wxPython (used in conjunction
+	with -wthread). Requires the wxversion module, part of recent
+	wxPython distributions
+
+    -xmode <modename>
+
+	Mode for exception reporting.
+
+	Valid modes: Plain, Context and Verbose.
+
+	* Plain: similar to python's normal traceback printing.
+	* Context: prints 5 lines of context source code around each
+	  line in the traceback.
+	* Verbose: similar to Context, but additionally prints the
+	  variables currently visible where the exception happened
+	  (shortening their strings if too long). This can potentially be
+	  very slow, if you happen to have a huge data structure whose
+	  string representation is complex to compute. Your computer may
+	  appear to freeze for a while with cpu usage at 100%. If this
+	  occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
+	  more than once).
+
+Interactive use
+===============
+
+Warning: IPython relies on the existence of a global variable called
+_ip which controls the shell itself. If you redefine _ip to anything,
+bizarre behavior will quickly occur.
+
+Other than the above warning, IPython is meant to work as a drop-in
+replacement for the standard interactive interpreter. As such, any code
+which is valid python should execute normally under IPython (cases where
+this is not true should be reported as bugs). It does, however, offer
+many features which are not available at a standard python prompt. What
+follows is a list of these.
+
+
+Caution for Windows users
+-------------------------
+
+Windows, unfortunately, uses the '\' character as a path
+separator. This is a terrible choice, because '\' also represents the
+escape character in most modern programming languages, including
+Python. For this reason, using '/' character is recommended if you
+have problems with ``\``.  However, in Windows commands '/' flags
+options, so you can not use it for the root directory. This means that
+paths beginning at the root must be typed in a contrived manner like:
+``%copy \opt/foo/bar.txt \tmp``
+
+.. _magic:
+
+Magic command system
+--------------------
+
+IPython will treat any line whose first character is a % as a special
+call to a 'magic' function. These allow you to control the behavior of
+IPython itself, plus a lot of system-type features. They are all
+prefixed with a % character, but parameters are given without
+parentheses or quotes.
+
+Example: typing '%cd mydir' (without the quotes) changes you working
+directory to 'mydir', if it exists.
+
+If you have 'automagic' enabled (in your ipythonrc file, via the command
+line option -automagic or with the %automagic function), you don't need
+to type in the % explicitly. IPython will scan its internal list of
+magic functions and call one if it exists. With automagic on you can
+then just type 'cd mydir' to go to directory 'mydir'. The automagic
+system has the lowest possible precedence in name searches, so defining
+an identifier with the same name as an existing magic function will
+shadow it for automagic use. You can still access the shadowed magic
+function by explicitly using the % character at the beginning of the line.
+
+An example (with automagic on) should clarify all this::
+
+    In [1]: cd ipython # %cd is called by automagic
+
+    /home/fperez/ipython
+
+    In [2]: cd=1 # now cd is just a variable
+
+    In [3]: cd .. # and doesn't work as a function anymore
+
+    ------------------------------
+
+        File "<console>", line 1
+
+          cd ..
+
+              ^
+
+    SyntaxError: invalid syntax
+
+    In [4]: %cd .. # but %cd always works
+
+    /home/fperez
+
+    In [5]: del cd # if you remove the cd variable
+
+    In [6]: cd ipython # automagic can work again
+
+    /home/fperez/ipython
+
+You can define your own magic functions to extend the system. The
+following example defines a new magic command, %impall::
+
+    import IPython.ipapi 
+
+    ip = IPython.ipapi.get()
+
+    def doimp(self, arg):
+
+        ip = self.api
+
+        ip.ex("import %s; reload(%s); from %s import *" % (
+
+        arg,arg,arg)
+
+        )
+
+    ip.expose_magic('impall', doimp)
+
+You can also define your own aliased names for magic functions. In your
+ipythonrc file, placing a line like:
+
+execute __IP.magic_cl = __IP.magic_clear
+
+will define %cl as a new name for %clear.
+
+Type %magic for more information, including a list of all available
+magic functions at any time and their docstrings. You can also type
+%magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
+information on the '?' system) to get information about any particular
+magic function you are interested in.
+
+
+Magic commands
+--------------
+
+The rest of this section is automatically generated for each release
+from the docstrings in the IPython code. Therefore the formatting is
+somewhat minimal, but this method has the advantage of having
+information always in sync with the code.
+
+A list of all the magic commands available in IPython's default
+installation follows. This is similar to what you'll see by simply
+typing %magic at the prompt, but that will also give you information
+about magic commands you may have added as part of your personal
+customizations.
+
+.. magic_start
+
+**%Exit**::
+
+	Exit IPython without confirmation.
+
+**%Pprint**::
+
+	Toggle pretty printing on/off.
+
+**%alias**::
+
+	Define an alias for a system command.
+
+        '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
+
+        Then, typing 'alias_name params' will execute the system command 'cmd
+        params' (from your underlying operating system).
+
+        Aliases have lower precedence than magic functions and Python normal
+        variables, so if 'foo' is both a Python variable and an alias, the
+        alias can not be executed until 'del foo' removes the Python variable.
+
+        You can use the %l specifier in an alias definition to represent the
+        whole line when the alias is called.  For example:
+
+          In [2]: alias all echo "Input in brackets: <%l>"\
+          In [3]: all hello world\
+          Input in brackets: <hello world>
+
+        You can also define aliases with parameters using %s specifiers (one
+        per parameter):
+        
+          In [1]: alias parts echo first %s second %s\
+          In [2]: %parts A B\
+          first A second B\
+          In [3]: %parts A\
+          Incorrect number of arguments: 2 expected.\
+          parts is an alias to: 'echo first %s second %s'
+
+        Note that %l and %s are mutually exclusive.  You can only use one or
+        the other in your aliases.
+
+        Aliases expand Python variables just like system calls using ! or !! 
+        do: all expressions prefixed with '$' get expanded.  For details of
+        the semantic rules, see PEP-215:
+        http://www.python.org/peps/pep-0215.html.  This is the library used by
+        IPython for variable expansion.  If you want to access a true shell
+        variable, an extra $ is necessary to prevent its expansion by IPython:
+
+        In [6]: alias show echo\
+        In [7]: PATH='A Python string'\
+        In [8]: show $PATH\
+        A Python string\
+        In [9]: show $$PATH\
+        /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
+
+        You can use the alias facility to acess all of $PATH.  See the %rehash
+        and %rehashx functions, which automatically create aliases for the
+        contents of your $PATH.
+
+        If called with no parameters, %alias prints the current alias table.
+
+**%autocall**::
+
+	Make functions callable without having to type parentheses.
+
+        Usage:
+
+           %autocall [mode]
+
+        The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
+        value is toggled on and off (remembering the previous state).
+
+        In more detail, these values mean:
+
+        0 -> fully disabled
+
+        1 -> active, but do not apply if there are no arguments on the line.
+
+        In this mode, you get:
+
+        In [1]: callable
+        Out[1]: <built-in function callable>
+
+        In [2]: callable 'hello'
+        ------> callable('hello')
+        Out[2]: False
+
+        2 -> Active always.  Even if no arguments are present, the callable
+        object is called:
+
+        In [4]: callable
+        ------> callable()
+
+        Note that even with autocall off, you can still use '/' at the start of
+        a line to treat the first argument on the command line as a function
+        and add parentheses to it:
+
+        In [8]: /str 43
+        ------> str(43)
+        Out[8]: '43'
+
+**%autoindent**::
+
+	Toggle autoindent on/off (if available).
+
+**%automagic**::
+
+	Make magic functions callable without having to type the initial %.
+
+        Without argumentsl toggles on/off (when off, you must call it as
+        %automagic, of course).  With arguments it sets the value, and you can
+        use any of (case insensitive):
+
+         - on,1,True: to activate
+
+         - off,0,False: to deactivate.
+
+        Note that magic functions have lowest priority, so if there's a
+        variable whose name collides with that of a magic fn, automagic won't
+        work for that function (you get the variable instead). However, if you
+        delete the variable (del var), the previously shadowed magic function
+        becomes visible to automagic again.
+
+**%bg**::
+
+	Run a job in the background, in a separate thread.
+
+        For example,
+
+          %bg myfunc(x,y,z=1)
+
+        will execute 'myfunc(x,y,z=1)' in a background thread.  As soon as the
+        execution starts, a message will be printed indicating the job
+        number.  If your job number is 5, you can use
+
+          myvar = jobs.result(5)  or  myvar = jobs[5].result
+
+        to assign this result to variable 'myvar'.
+
+        IPython has a job manager, accessible via the 'jobs' object.  You can
+        type jobs? to get more information about it, and use jobs.<TAB> to see
+        its attributes.  All attributes not starting with an underscore are
+        meant for public use.
+
+        In particular, look at the jobs.new() method, which is used to create
+        new jobs.  This magic %bg function is just a convenience wrapper
+        around jobs.new(), for expression-based jobs.  If you want to create a
+        new job with an explicit function object and arguments, you must call
+        jobs.new() directly.
+
+        The jobs.new docstring also describes in detail several important
+        caveats associated with a thread-based model for background job
+        execution.  Type jobs.new? for details.
+
+        You can check the status of all jobs with jobs.status().
+
+        The jobs variable is set by IPython into the Python builtin namespace.
+        If you ever declare a variable named 'jobs', you will shadow this
+        name.  You can either delete your global jobs variable to regain
+        access to the job manager, or make a new name and assign it manually
+        to the manager (stored in IPython's namespace).  For example, to
+        assign the job manager to the Jobs name, use:
+
+          Jobs = __builtins__.jobs
+
+**%bookmark**::
+
+	Manage IPython's bookmark system.
+
+        %bookmark <name>       - set bookmark to current dir
+        %bookmark <name> <dir> - set bookmark to <dir>
+        %bookmark -l           - list all bookmarks
+        %bookmark -d <name>    - remove bookmark
+        %bookmark -r           - remove all bookmarks
+
+        You can later on access a bookmarked folder with:
+          %cd -b <name>
+        or simply '%cd <name>' if there is no directory called <name> AND
+        there is such a bookmark defined.
+
+        Your bookmarks persist through IPython sessions, but they are
+        associated with each profile.
+
+**%cd**::
+
+	Change the current working directory.
+
+        This command automatically maintains an internal list of directories
+        you visit during your IPython session, in the variable _dh. The
+        command %dhist shows this history nicely formatted. You can also
+        do 'cd -<tab>' to see directory history conveniently.
+
+        Usage:
+
+          cd 'dir': changes to directory 'dir'.
+
+          cd -: changes to the last visited directory.
+
+          cd -<n>: changes to the n-th directory in the directory history.
+
+          cd -b <bookmark_name>: jump to a bookmark set by %bookmark
+             (note: cd <bookmark_name> is enough if there is no
+              directory <bookmark_name>, but a bookmark with the name exists.)
+              'cd -b <tab>' allows you to tab-complete bookmark names. 
+
+        Options:
+
+        -q: quiet.  Do not print the working directory after the cd command is
+        executed.  By default IPython's cd command does print this directory,
+        since the default prompts do not display path information.
+        
+        Note that !cd doesn't work for this purpose because the shell where
+        !command runs is immediately discarded after executing 'command'.
+
+**%clear**::
+
+	 Clear various data (e.g. stored history data)
+    
+    %clear out - clear output history
+    %clear in  - clear input history
+    %clear shadow_compress - Compresses shadow history (to speed up ipython)
+    %clear shadow_nuke - permanently erase all entries in shadow history
+    %clear dhist - clear dir history
+
+**%color_info**::
+
+	Toggle color_info.
+
+        The color_info configuration parameter controls whether colors are
+        used for displaying object details (by things like %psource, %pfile or
+        the '?' system). This function toggles this value with each call.
+
+        Note that unless you have a fairly recent pager (less works better
+        than more) in your system, using colored object information displays
+        will not work properly. Test it and see.
+
+**%colors**::
+
+	Switch color scheme for prompts, info system and exception handlers.
+
+        Currently implemented schemes: NoColor, Linux, LightBG.
+
+        Color scheme names are not case-sensitive.
+
+**%cpaste**::
+
+	Allows you to paste & execute a pre-formatted code block from clipboard
+        
+        You must terminate the block with '--' (two minus-signs) alone on the
+        line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
+        is the new sentinel for this operation)
+        
+        The block is dedented prior to execution to enable execution of method
+        definitions. '>' and '+' characters at the beginning of a line are
+        ignored, to allow pasting directly from e-mails or diff files. The
+        executed block is also assigned to variable named 'pasted_block' for
+        later editing with '%edit pasted_block'.
+        
+        You can also pass a variable name as an argument, e.g. '%cpaste foo'.
+        This assigns the pasted block to variable 'foo' as string, without 
+        dedenting or executing it.
+        
+        Do not be alarmed by garbled output on Windows (it's a readline bug). 
+        Just press enter and type -- (and press enter again) and the block 
+        will be what was just pasted.
+        
+        IPython statements (magics, shell escapes) are not supported (yet).
+
+**%debug**::
+
+	Activate the interactive debugger in post-mortem mode.
+
+        If an exception has just occurred, this lets you inspect its stack
+        frames interactively.  Note that this will always work only on the last
+        traceback that occurred, so you must call this quickly after an
+        exception that you wish to inspect has fired, because if another one
+        occurs, it clobbers the previous one.
+
+        If you want IPython to automatically do this on every exception, see
+        the %pdb magic for more details.
+
+**%dhist**::
+
+	Print your history of visited directories.
+
+        %dhist       -> print full history\
+        %dhist n     -> print last n entries only\
+        %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
+
+        This history is automatically maintained by the %cd command, and
+        always available as the global list variable _dh. You can use %cd -<n>
+        to go to directory number <n>.
+        
+        Note that most of time, you should view directory history by entering
+        cd -<TAB>.
+
+**%dirs**::
+
+	Return the current directory stack.
+
+**%doctest_mode**::
+
+	Toggle doctest mode on and off.
+
+        This mode allows you to toggle the prompt behavior between normal
+        IPython prompts and ones that are as similar to the default IPython
+        interpreter as possible.
+
+        It also supports the pasting of code snippets that have leading '>>>'
+        and '...' prompts in them.  This means that you can paste doctests from
+        files or docstrings (even if they have leading whitespace), and the
+        code will execute correctly.  You can then use '%history -tn' to see
+        the translated history without line numbers; this will give you the
+        input after removal of all the leading prompts and whitespace, which
+        can be pasted back into an editor.
+
+        With these features, you can switch into this mode easily whenever you
+        need to do testing and changes to doctests, without having to leave
+        your existing IPython session.
+
+**%ed**::
+
+	Alias to %edit.
+
+**%edit**::
+
+	Bring up an editor and execute the resulting code.
+
+        Usage:
+          %edit [options] [args]
+
+        %edit runs IPython's editor hook.  The default version of this hook is
+        set to call the __IPYTHON__.rc.editor command.  This is read from your
+        environment variable $EDITOR.  If this isn't found, it will default to
+        vi under Linux/Unix and to notepad under Windows.  See the end of this
+        docstring for how to change the editor hook.
+
+        You can also set the value of this editor via the command line option
+        '-editor' or in your ipythonrc file. This is useful if you wish to use
+        specifically for IPython an editor different from your typical default
+        (and for Windows users who typically don't set environment variables).
+
+        This command allows you to conveniently edit multi-line code right in
+        your IPython session.
+        
+        If called without arguments, %edit opens up an empty editor with a
+        temporary file and will execute the contents of this file when you
+        close it (don't forget to save it!).
+
+
+        Options:
+
+        -n <number>: open the editor at a specified line number.  By default,
+        the IPython editor hook uses the unix syntax 'editor +N filename', but
+        you can configure this by providing your own modified hook if your
+        favorite editor supports line-number specifications with a different
+        syntax.
+        
+        -p: this will call the editor with the same data as the previous time
+        it was used, regardless of how long ago (in your current session) it
+        was.
+
+        -r: use 'raw' input.  This option only applies to input taken from the
+        user's history.  By default, the 'processed' history is used, so that
+        magics are loaded in their transformed version to valid Python.  If
+        this option is given, the raw input as typed as the command line is
+        used instead.  When you exit the editor, it will be executed by
+        IPython's own processor.
+        
+        -x: do not execute the edited code immediately upon exit. This is
+        mainly useful if you are editing programs which need to be called with
+        command line arguments, which you can then do using %run.
+
+
+        Arguments:
+
+        If arguments are given, the following possibilites exist:
+
+        - The arguments are numbers or pairs of colon-separated numbers (like
+        1 4:8 9). These are interpreted as lines of previous input to be
+        loaded into the editor. The syntax is the same of the %macro command.
+
+        - If the argument doesn't start with a number, it is evaluated as a
+        variable and its contents loaded into the editor. You can thus edit
+        any string which contains python code (including the result of
+        previous edits).
+
+        - If the argument is the name of an object (other than a string),
+        IPython will try to locate the file where it was defined and open the
+        editor at the point where it is defined. You can use `%edit function`
+        to load an editor exactly at the point where 'function' is defined,
+        edit it and have the file be executed automatically.
+
+        If the object is a macro (see %macro for details), this opens up your
+        specified editor with a temporary file containing the macro's data.
+        Upon exit, the macro is reloaded with the contents of the file.
+
+        Note: opening at an exact line is only supported under Unix, and some
+        editors (like kedit and gedit up to Gnome 2.8) do not understand the
+        '+NUMBER' parameter necessary for this feature. Good editors like
+        (X)Emacs, vi, jed, pico and joe all do.
+
+        - If the argument is not found as a variable, IPython will look for a
+        file with that name (adding .py if necessary) and load it into the
+        editor. It will execute its contents with execfile() when you exit,
+        loading any code in the file into your interactive namespace.
+
+        After executing your code, %edit will return as output the code you
+        typed in the editor (except when it was an existing file). This way
+        you can reload the code in further invocations of %edit as a variable,
+        via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
+        the output.
+
+        Note that %edit is also available through the alias %ed.
+
+        This is an example of creating a simple function inside the editor and
+        then modifying it. First, start up the editor:
+
+        In [1]: ed\
+        Editing... done. Executing edited code...\
+        Out[1]: 'def foo():\n    print "foo() was defined in an editing session"\n'
+
+        We can then call the function foo():
+        
+        In [2]: foo()\
+        foo() was defined in an editing session
+
+        Now we edit foo.  IPython automatically loads the editor with the
+        (temporary) file where foo() was previously defined:
+        
+        In [3]: ed foo\
+        Editing... done. Executing edited code...
+
+        And if we call foo() again we get the modified version:
+        
+        In [4]: foo()\
+        foo() has now been changed!
+
+        Here is an example of how to edit a code snippet successive
+        times. First we call the editor:
+
+        In [8]: ed\
+        Editing... done. Executing edited code...\
+        hello\
+        Out[8]: "print 'hello'\n"
+
+        Now we call it again with the previous output (stored in _):
+
+        In [9]: ed _\
+        Editing... done. Executing edited code...\
+        hello world\
+        Out[9]: "print 'hello world'\n"
+
+        Now we call it with the output #8 (stored in _8, also as Out[8]):
+
+        In [10]: ed _8\
+        Editing... done. Executing edited code...\
+        hello again\
+        Out[10]: "print 'hello again'\n"
+
+
+        Changing the default editor hook:
+
+        If you wish to write your own editor hook, you can put it in a
+        configuration file which you load at startup time.  The default hook
+        is defined in the IPython.hooks module, and you can use that as a
+        starting example for further modifications.  That file also has
+        general instructions on how to set a new hook for use once you've
+        defined it.
+
+**%env**::
+
+	List environment variables.
+
+**%exit**::
+
+	Exit IPython, confirming if configured to do so.
+
+        You can configure whether IPython asks for confirmation upon exit by
+        setting the confirm_exit flag in the ipythonrc file.
+
+**%hist**::
+
+	Alternate name for %history.
+
+**%history**::
+
+	Print input history (_i<n> variables), with most recent last.
+    
+    %history       -> print at most 40 inputs (some may be multi-line)\
+    %history n     -> print at most n inputs\
+    %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
+    
+    Each input's number <n> is shown, and is accessible as the
+    automatically generated variable _i<n>.  Multi-line statements are
+    printed starting at a new line for easy copy/paste.
+    
+
+    Options:
+
+      -n: do NOT print line numbers. This is useful if you want to get a
+      printout of many lines which can be directly pasted into a text
+      editor.
+
+      This feature is only available if numbered prompts are in use.
+
+      -t: (default) print the 'translated' history, as IPython understands it.
+      IPython filters your input and converts it all into valid Python source
+      before executing it (things like magics or aliases are turned into
+      function calls, for example). With this option, you'll see the native
+      history instead of the user-entered version: '%cd /' will be seen as
+      '_ip.magic("%cd /")' instead of '%cd /'.
+      
+      -r: print the 'raw' history, i.e. the actual commands you typed.
+      
+      -g: treat the arg as a pattern to grep for in (full) history.
+      This includes the "shadow history" (almost all commands ever written).
+      Use '%hist -g' to show full shadow history (may be very long).
+      In shadow history, every index nuwber starts with 0.
+
+      -f FILENAME: instead of printing the output to the screen, redirect it to
+       the given file.  The file is always overwritten, though IPython asks for
+       confirmation first if it already exists.
+
+**%logoff**::
+
+	Temporarily stop logging.
+
+        You must have previously started logging.
+
+**%logon**::
+
+	Restart logging.
+
+        This function is for restarting logging which you've temporarily
+        stopped with %logoff. For starting logging for the first time, you
+        must use the %logstart function, which allows you to specify an
+        optional log filename.
+
+**%logstart**::
+
+	Start logging anywhere in a session.
+
+        %logstart [-o|-r|-t] [log_name [log_mode]]
+
+        If no name is given, it defaults to a file named 'ipython_log.py' in your
+        current directory, in 'rotate' mode (see below).
+
+        '%logstart name' saves to file 'name' in 'backup' mode.  It saves your
+        history up to that point and then continues logging.
+
+        %logstart takes a second optional parameter: logging mode. This can be one
+        of (note that the modes are given unquoted):\
+          append: well, that says it.\
+          backup: rename (if exists) to name~ and start name.\
+          global: single logfile in your home dir, appended to.\
+          over  : overwrite existing log.\
+          rotate: create rotating logs name.1~, name.2~, etc.
+
+        Options:
+
+          -o: log also IPython's output.  In this mode, all commands which
+          generate an Out[NN] prompt are recorded to the logfile, right after
+          their corresponding input line.  The output lines are always
+          prepended with a '#[Out]# ' marker, so that the log remains valid
+          Python code.
+
+          Since this marker is always the same, filtering only the output from
+          a log is very easy, using for example a simple awk call:
+
+            awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
+
+          -r: log 'raw' input.  Normally, IPython's logs contain the processed
+          input, so that user lines are logged in their final form, converted
+          into valid Python.  For example, %Exit is logged as
+          '_ip.magic("Exit").  If the -r flag is given, all input is logged
+          exactly as typed, with no transformations applied.
+
+          -t: put timestamps before each input line logged (these are put in
+          comments).
+
+**%logstate**::
+
+	Print the status of the logging system.
+
+**%logstop**::
+
+	Fully stop logging and close log file.
+
+        In order to start logging again, a new %logstart call needs to be made,
+        possibly (though not necessarily) with a new filename, mode and other
+        options.
+
+**%lsmagic**::
+
+	List currently available magic functions.
+
+**%macro**::
+
+	Define a set of input lines as a macro for future re-execution.
+
+        Usage:\
+          %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
+
+        Options:
+        
+          -r: use 'raw' input.  By default, the 'processed' history is used,
+          so that magics are loaded in their transformed version to valid
+          Python.  If this option is given, the raw input as typed as the
+          command line is used instead.
+
+        This will define a global variable called `name` which is a string
+        made of joining the slices and lines you specify (n1,n2,... numbers
+        above) from your input history into a single string. This variable
+        acts like an automatic function which re-executes those lines as if
+        you had typed them. You just type 'name' at the prompt and the code
+        executes.
+
+        The notation for indicating number ranges is: n1-n2 means 'use line
+        numbers n1,...n2' (the endpoint is included).  That is, '5-7' means
+        using the lines numbered 5,6 and 7.
+
+        Note: as a 'hidden' feature, you can also use traditional python slice
+        notation, where N:M means numbers N through M-1.
+
+        For example, if your history contains (%hist prints it):
+        
+          44: x=1\
+          45: y=3\
+          46: z=x+y\
+          47: print x\
+          48: a=5\
+          49: print 'x',x,'y',y\
+
+        you can create a macro with lines 44 through 47 (included) and line 49
+        called my_macro with:
+
+          In [51]: %macro my_macro 44-47 49
+
+        Now, typing `my_macro` (without quotes) will re-execute all this code
+        in one pass.
+
+        You don't need to give the line-numbers in order, and any given line
+        number can appear multiple times. You can assemble macros with any
+        lines from your input history in any order.
+
+        The macro is a simple object which holds its value in an attribute,
+        but IPython's display system checks for macros and executes them as
+        code instead of printing them when you type their name.
+
+        You can view a macro's contents by explicitly printing it with:
+        
+          'print macro_name'.
+
+        For one-off cases which DON'T contain magic function calls in them you
+        can obtain similar results by explicitly executing slices from your
+        input history with:
+
+          In [60]: exec In[44:48]+In[49]
+
+**%magic**::
+
+	Print information about the magic function system.
+
+**%mglob**::
+
+	    This program allows specifying filenames with "mglob" mechanism.
+    Supported syntax in globs (wilcard matching patterns)::
+    
+     *.cpp ?ellowo*                
+         - obvious. Differs from normal glob in that dirs are not included.
+           Unix users might want to write this as: "*.cpp" "?ellowo*"
+     rec:/usr/share=*.txt,*.doc    
+         - get all *.txt and *.doc under /usr/share, 
+           recursively
+     rec:/usr/share
+         - All files under /usr/share, recursively
+     rec:*.py
+         - All .py files under current working dir, recursively
+     foo                           
+         - File or dir foo
+     !*.bak readme*                   
+         - readme*, exclude files ending with .bak
+     !.svn/ !.hg/ !*_Data/ rec:.
+         - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
+           Trailing / is the key, \ does not work!
+     dir:foo                       
+         - the directory foo if it exists (not files in foo)
+     dir:*                         
+         - all directories in current folder
+     foo.py bar.* !h* rec:*.py
+         - Obvious. !h* exclusion only applies for rec:*.py.
+           foo.py is *not* included twice.
+     @filelist.txt
+         - All files listed in 'filelist.txt' file, on separate lines.
+
+**%page**::
+
+	Pretty print the object and display it through a pager.
+        
+        %page [options] OBJECT
+
+        If no object is given, use _ (last output).
+        
+        Options:
+
+          -r: page str(object), don't pretty-print it.
+
+**%pdb**::
+
+	Control the automatic calling of the pdb interactive debugger.
+
+        Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
+        argument it works as a toggle.
+
+        When an exception is triggered, IPython can optionally call the
+        interactive pdb debugger after the traceback printout. %pdb toggles
+        this feature on and off.
+
+        The initial state of this feature is set in your ipythonrc
+        configuration file (the variable is called 'pdb').
+
+        If you want to just activate the debugger AFTER an exception has fired,
+        without having to type '%pdb on' and rerunning your code, you can use
+        the %debug magic.
+
+**%pdef**::
+
+	Print the definition header for any callable object.
+
+        If the object is a class, print the constructor information.
+
+**%pdoc**::
+
+	Print the docstring for an object.
+
+        If the given object is a class, it will print both the class and the
+        constructor docstrings.
+
+**%pfile**::
+
+	Print (or run through pager) the file where an object is defined.
+
+        The file opens at the line where the object definition begins. IPython
+        will honor the environment variable PAGER if set, and otherwise will
+        do its best to print the file in a convenient form.
+
+        If the given argument is not an object currently defined, IPython will
+        try to interpret it as a filename (automatically adding a .py extension
+        if needed). You can thus use %pfile as a syntax highlighting code
+        viewer.
+
+**%pinfo**::
+
+	Provide detailed information about an object.
+    
+        '%pinfo object' is just a synonym for object? or ?object.
+
+**%popd**::
+
+	Change to directory popped off the top of the stack.
+
+**%profile**::
+
+	Print your currently active IPyhton profile.
+
+**%prun**::
+
+	Run a statement through the python code profiler.
+
+        Usage:\
+          %prun [options] statement
+
+        The given statement (which doesn't require quote marks) is run via the
+        python profiler in a manner similar to the profile.run() function.
+        Namespaces are internally managed to work correctly; profile.run
+        cannot be used in IPython because it makes certain assumptions about
+        namespaces which do not hold under IPython.
+
+        Options:
+
+        -l <limit>: you can place restrictions on what or how much of the
+        profile gets printed. The limit value can be:
+
+          * A string: only information for function names containing this string
+          is printed.
+
+          * An integer: only these many lines are printed.
+
+          * A float (between 0 and 1): this fraction of the report is printed
+          (for example, use a limit of 0.4 to see the topmost 40% only).
+
+        You can combine several limits with repeated use of the option. For
+        example, '-l __init__ -l 5' will print only the topmost 5 lines of
+        information about class constructors.
+
+        -r: return the pstats.Stats object generated by the profiling. This
+        object has all the information about the profile in it, and you can
+        later use it for further analysis or in other functions.
+
+       -s <key>: sort profile by given key. You can provide more than one key
+        by using the option several times: '-s key1 -s key2 -s key3...'. The
+        default sorting key is 'time'.
+
+        The following is copied verbatim from the profile documentation
+        referenced below:
+
+        When more than one key is provided, additional keys are used as
+        secondary criteria when the there is equality in all keys selected
+        before them.
+        
+        Abbreviations can be used for any key names, as long as the
+        abbreviation is unambiguous.  The following are the keys currently
+        defined:
+
+                Valid Arg       Meaning\
+                  "calls"      call count\
+                  "cumulative" cumulative time\
+                  "file"       file name\
+                  "module"     file name\
+                  "pcalls"     primitive call count\
+                  "line"       line number\
+                  "name"       function name\
+                  "nfl"        name/file/line\
+                  "stdname"    standard name\
+                  "time"       internal time
+
+        Note that all sorts on statistics are in descending order (placing
+        most time consuming items first), where as name, file, and line number
+        searches are in ascending order (i.e., alphabetical). The subtle
+        distinction between "nfl" and "stdname" is that the standard name is a
+        sort of the name as printed, which means that the embedded line
+        numbers get compared in an odd way.  For example, lines 3, 20, and 40
+        would (if the file names were the same) appear in the string order
+        "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
+        line numbers.  In fact, sort_stats("nfl") is the same as
+        sort_stats("name", "file", "line").
+
+        -T <filename>: save profile results as shown on screen to a text
+        file. The profile is still shown on screen.
+
+        -D <filename>: save (via dump_stats) profile statistics to given
+        filename. This data is in a format understod by the pstats module, and
+        is generated by a call to the dump_stats() method of profile
+        objects. The profile is still shown on screen.
+
+        If you want to run complete programs under the profiler's control, use
+        '%run -p [prof_opts] filename.py [args to program]' where prof_opts
+        contains profiler specific options as described here.
+        
+        You can read the complete documentation for the profile module with:\
+          In [1]: import profile; profile.help()
+
+**%psearch**::
+
+	Search for object in namespaces by wildcard.
+
+        %psearch [options] PATTERN [OBJECT TYPE]
+
+        Note: ? can be used as a synonym for %psearch, at the beginning or at
+        the end: both a*? and ?a* are equivalent to '%psearch a*'.  Still, the
+        rest of the command line must be unchanged (options come first), so
+        for example the following forms are equivalent
+
+        %psearch -i a* function
+        -i a* function?
+        ?-i a* function
+
+        Arguments:
+        
+          PATTERN
+
+          where PATTERN is a string containing * as a wildcard similar to its
+          use in a shell.  The pattern is matched in all namespaces on the
+          search path. By default objects starting with a single _ are not
+          matched, many IPython generated objects have a single
+          underscore. The default is case insensitive matching. Matching is
+          also done on the attributes of objects and not only on the objects
+          in a module.
+
+          [OBJECT TYPE]
+
+          Is the name of a python type from the types module. The name is
+          given in lowercase without the ending type, ex. StringType is
+          written string. By adding a type here only objects matching the
+          given type are matched. Using all here makes the pattern match all
+          types (this is the default).
+
+        Options:
+
+          -a: makes the pattern match even objects whose names start with a
+          single underscore.  These names are normally ommitted from the
+          search.
+
+          -i/-c: make the pattern case insensitive/sensitive.  If neither of
+          these options is given, the default is read from your ipythonrc
+          file.  The option name which sets this value is
+          'wildcards_case_sensitive'.  If this option is not specified in your
+          ipythonrc file, IPython's internal default is to do a case sensitive
+          search.
+
+          -e/-s NAMESPACE: exclude/search a given namespace.  The pattern you
+          specifiy can be searched in any of the following namespaces:
+          'builtin', 'user', 'user_global','internal', 'alias', where
+          'builtin' and 'user' are the search defaults.  Note that you should
+          not use quotes when specifying namespaces.
+
+          'Builtin' contains the python module builtin, 'user' contains all
+          user data, 'alias' only contain the shell aliases and no python
+          objects, 'internal' contains objects used by IPython.  The
+          'user_global' namespace is only used by embedded IPython instances,
+          and it contains module-level globals.  You can add namespaces to the
+          search with -s or exclude them with -e (these options can be given
+          more than once).
+    
+        Examples:
+       
+        %psearch a*            -> objects beginning with an a
+        %psearch -e builtin a* -> objects NOT in the builtin space starting in a
+        %psearch a* function   -> all functions beginning with an a
+        %psearch re.e*         -> objects beginning with an e in module re
+        %psearch r*.e*         -> objects that start with e in modules starting in r
+        %psearch r*.* string   -> all strings in modules beginning with r
+
+        Case sensitve search:
+       
+        %psearch -c a*         list all object beginning with lower case a
+
+        Show objects beginning with a single _:
+       
+        %psearch -a _*         list objects beginning with a single underscore
+
+**%psource**::
+
+	Print (or run through pager) the source code for an object.
+
+**%pushd**::
+
+	Place the current dir on stack and change directory.
+        
+        Usage:\
+          %pushd ['dirname']
+
+**%pwd**::
+
+	Return the current working directory path.
+
+**%pycat**::
+
+	Show a syntax-highlighted file through a pager.
+
+        This magic is similar to the cat utility, but it will assume the file
+        to be Python source and will show it with syntax highlighting.
+
+**%quickref**::
+
+	 Show a quick reference sheet
+
+**%quit**::
+
+	Exit IPython, confirming if configured to do so (like %exit)
+
+**%r**::
+
+	Repeat previous input.
+
+        Note: Consider using the more powerfull %rep instead!
+        
+        If given an argument, repeats the previous command which starts with
+        the same string, otherwise it just repeats the previous input.
+
+        Shell escaped commands (with ! as first character) are not recognized
+        by this system, only pure python code and magic commands.
+
+**%rehashdir**::
+
+	 Add executables in all specified dirs to alias table
+     
+    Usage:
+
+    %rehashdir c:/bin;c:/tools
+      - Add all executables under c:/bin and c:/tools to alias table, in 
+      order to make them directly executable from any directory.
+        
+      Without arguments, add all executables in current directory.
+
+**%rehashx**::
+
+	Update the alias table with all executable files in $PATH.
+
+        This version explicitly checks that every entry in $PATH is a file
+        with execute access (os.X_OK), so it is much slower than %rehash.
+
+        Under Windows, it checks executability as a match agains a
+        '|'-separated string of extensions, stored in the IPython config
+        variable win_exec_ext.  This defaults to 'exe|com|bat'.
+        
+        This function also resets the root module cache of module completer,
+        used on slow filesystems.
+
+**%rep**::
+
+	 Repeat a command, or get command to input line for editing
+
+    - %rep (no arguments):
+    
+    Place a string version of last computation result (stored in the special '_'
+    variable) to the next input prompt. Allows you to create elaborate command
+    lines without using copy-paste::
+    
+        $ l = ["hei", "vaan"]       
+        $ "".join(l)        
+        ==> heivaan        
+        $ %rep        
+        $ heivaan_ <== cursor blinking    
+    
+    %rep 45
+    
+    Place history line 45 to next input prompt. Use %hist to find out the
+    number.
+    
+    %rep 1-4 6-7 3
+    
+    Repeat the specified lines immediately. Input slice syntax is the same as
+    in %macro and %save.
+    
+    %rep foo
+    
+    Place the most recent line that has the substring "foo" to next input.
+    (e.g. 'svn ci -m foobar').
+
+**%reset**::
+
+	Resets the namespace by removing all names defined by the user.
+
+        Input/Output history are left around in case you need them.
+
+**%run**::
+
+	Run the named file inside IPython as a program.
+
+        Usage:\
+          %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
+        
+        Parameters after the filename are passed as command-line arguments to
+        the program (put in sys.argv). Then, control returns to IPython's
+        prompt.
+
+        This is similar to running at a system prompt:\
+          $ python file args\
+        but with the advantage of giving you IPython's tracebacks, and of
+        loading all variables into your interactive namespace for further use
+        (unless -p is used, see below).
+
+        The file is executed in a namespace initially consisting only of
+        __name__=='__main__' and sys.argv constructed as indicated. It thus
+        sees its environment as if it were being run as a stand-alone program
+        (except for sharing global objects such as previously imported
+        modules). But after execution, the IPython interactive namespace gets
+        updated with all variables defined in the program (except for __name__
+        and sys.argv). This allows for very convenient loading of code for
+        interactive work, while giving each program a 'clean sheet' to run in.
+
+        Options:
+        
+        -n: __name__ is NOT set to '__main__', but to the running file's name
+        without extension (as python does under import).  This allows running
+        scripts and reloading the definitions in them without calling code
+        protected by an ' if __name__ == "__main__" ' clause.
+
+        -i: run the file in IPython's namespace instead of an empty one. This
+        is useful if you are experimenting with code written in a text editor
+        which depends on variables defined interactively.
+
+        -e: ignore sys.exit() calls or SystemExit exceptions in the script
+        being run.  This is particularly useful if IPython is being used to
+        run unittests, which always exit with a sys.exit() call.  In such
+        cases you are interested in the output of the test results, not in
+        seeing a traceback of the unittest module.
+
+        -t: print timing information at the end of the run.  IPython will give
+        you an estimated CPU time consumption for your script, which under
+        Unix uses the resource module to avoid the wraparound problems of
+        time.clock().  Under Unix, an estimate of time spent on system tasks
+        is also given (for Windows platforms this is reported as 0.0).
+
+        If -t is given, an additional -N<N> option can be given, where <N>
+        must be an integer indicating how many times you want the script to
+        run.  The final timing report will include total and per run results.
+
+        For example (testing the script uniq_stable.py):
+
+            In [1]: run -t uniq_stable
+
+            IPython CPU timings (estimated):\
+              User  :    0.19597 s.\
+              System:        0.0 s.\
+
+            In [2]: run -t -N5 uniq_stable
+
+            IPython CPU timings (estimated):\
+            Total runs performed: 5\
+              Times :      Total       Per run\
+              User  :   0.910862 s,  0.1821724 s.\
+              System:        0.0 s,        0.0 s.
+
+        -d: run your program under the control of pdb, the Python debugger.
+        This allows you to execute your program step by step, watch variables,
+        etc.  Internally, what IPython does is similar to calling:
+        
+          pdb.run('execfile("YOURFILENAME")')
+
+        with a breakpoint set on line 1 of your file.  You can change the line
+        number for this automatic breakpoint to be <N> by using the -bN option
+        (where N must be an integer).  For example:
+
+          %run -d -b40 myscript
+
+        will set the first breakpoint at line 40 in myscript.py.  Note that
+        the first breakpoint must be set on a line which actually does
+        something (not a comment or docstring) for it to stop execution.
+
+        When the pdb debugger starts, you will see a (Pdb) prompt.  You must
+        first enter 'c' (without qoutes) to start execution up to the first
+        breakpoint.
+
+        Entering 'help' gives information about the use of the debugger.  You
+        can easily see pdb's full documentation with "import pdb;pdb.help()"
+        at a prompt.
+
+        -p: run program under the control of the Python profiler module (which
+        prints a detailed report of execution times, function calls, etc).
+
+        You can pass other options after -p which affect the behavior of the
+        profiler itself. See the docs for %prun for details.
+
+        In this mode, the program's variables do NOT propagate back to the
+        IPython interactive namespace (because they remain in the namespace
+        where the profiler executes them).
+
+        Internally this triggers a call to %prun, see its documentation for
+        details on the options available specifically for profiling.
+
+        There is one special usage for which the text above doesn't apply:
+        if the filename ends with .ipy, the file is run as ipython script,
+        just as if the commands were written on IPython prompt.
+
+**%runlog**::
+
+	Run files as logs.
+
+        Usage:\
+          %runlog file1 file2 ...
+
+        Run the named files (treating them as log files) in sequence inside
+        the interpreter, and return to the prompt.  This is much slower than
+        %run because each line is executed in a try/except block, but it
+        allows running files with syntax errors in them.
+
+        Normally IPython will guess when a file is one of its own logfiles, so
+        you can typically use %run even for logs. This shorthand allows you to
+        force any file to be treated as a log file.
+
+**%save**::
+
+	Save a set of lines to a given filename.
+
+        Usage:\
+          %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
+
+        Options:
+        
+          -r: use 'raw' input.  By default, the 'processed' history is used,
+          so that magics are loaded in their transformed version to valid
+          Python.  If this option is given, the raw input as typed as the
+          command line is used instead.
+
+        This function uses the same syntax as %macro for line extraction, but
+        instead of creating a macro it saves the resulting string to the
+        filename you specify.
+
+        It adds a '.py' extension to the file if you don't do so yourself, and
+        it asks for confirmation before overwriting existing files.
+
+**%sc**::
+
+	Shell capture - execute a shell command and capture its output.
+
+        DEPRECATED. Suboptimal, retained for backwards compatibility.
+        
+        You should use the form 'var = !command' instead. Example:
+         
+         "%sc -l myfiles = ls ~" should now be written as
+            
+         "myfiles = !ls ~"
+         
+        myfiles.s, myfiles.l and myfiles.n still apply as documented
+        below.
+
+        --
+        %sc [options] varname=command
+
+        IPython will run the given command using commands.getoutput(), and
+        will then update the user's interactive namespace with a variable
+        called varname, containing the value of the call.  Your command can
+        contain shell wildcards, pipes, etc.
+
+        The '=' sign in the syntax is mandatory, and the variable name you
+        supply must follow Python's standard conventions for valid names.
+        
+        (A special format without variable name exists for internal use)
+
+        Options:
+
+          -l: list output.  Split the output on newlines into a list before
+          assigning it to the given variable.  By default the output is stored
+          as a single string.
+
+          -v: verbose.  Print the contents of the variable.
+
+        In most cases you should not need to split as a list, because the
+        returned value is a special type of string which can automatically
+        provide its contents either as a list (split on newlines) or as a
+        space-separated string.  These are convenient, respectively, either
+        for sequential processing or to be passed to a shell command.
+
+        For example:
+
+            # Capture into variable a
+            In [9]: sc a=ls *py
+
+            # a is a string with embedded newlines
+            In [10]: a
+            Out[10]: 'setup.py win32_manual_post_install.py'
+
+            # which can be seen as a list:
+            In [11]: a.l
+            Out[11]: ['setup.py', 'win32_manual_post_install.py']
+
+            # or as a whitespace-separated string:
+            In [12]: a.s
+            Out[12]: 'setup.py win32_manual_post_install.py'
+
+            # a.s is useful to pass as a single command line:
+            In [13]: !wc -l $a.s
+              146 setup.py
+              130 win32_manual_post_install.py
+              276 total
+
+            # while the list form is useful to loop over:
+            In [14]: for f in a.l:
+               ....:      !wc -l $f
+               ....:
+            146 setup.py
+            130 win32_manual_post_install.py
+
+        Similiarly, the lists returned by the -l option are also special, in
+        the sense that you can equally invoke the .s attribute on them to
+        automatically get a whitespace-separated string from their contents:
+
+            In [1]: sc -l b=ls *py
+
+            In [2]: b
+            Out[2]: ['setup.py', 'win32_manual_post_install.py']
+
+            In [3]: b.s
+            Out[3]: 'setup.py win32_manual_post_install.py'
+
+        In summary, both the lists and strings used for ouptut capture have
+        the following special attributes:
+
+            .l (or .list) : value as list.
+            .n (or .nlstr): value as newline-separated string.
+            .s (or .spstr): value as space-separated string.
+
+**%store**::
+
+	Lightweight persistence for python variables.
+
+    Example:
+    
+    ville@badger[~]|1> A = ['hello',10,'world']\
+    ville@badger[~]|2> %store A\
+    ville@badger[~]|3> Exit
+    
+    (IPython session is closed and started again...)
+    
+    ville@badger:~$ ipython -p pysh\
+    ville@badger[~]|1> print A
+    
+    ['hello', 10, 'world']
+    
+    Usage:
+    
+    %store          - Show list of all variables and their current values\
+    %store <var>    - Store the *current* value of the variable to disk\
+    %store -d <var> - Remove the variable and its value from storage\
+    %store -z       - Remove all variables from storage\
+    %store -r       - Refresh all variables from store (delete current vals)\
+    %store foo >a.txt  - Store value of foo to new file a.txt\
+    %store foo >>a.txt - Append value of foo to file a.txt\   
+    
+    It should be noted that if you change the value of a variable, you
+    need to %store it again if you want to persist the new value.
+    
+    Note also that the variables will need to be pickleable; most basic
+    python types can be safely %stored.
+    
+    Also aliases can be %store'd across sessions.
+
+**%sx**::
+
+	Shell execute - run a shell command and capture its output.
+
+        %sx command
+
+        IPython will run the given command using commands.getoutput(), and
+        return the result formatted as a list (split on '\n').  Since the
+        output is _returned_, it will be stored in ipython's regular output
+        cache Out[N] and in the '_N' automatic variables.
+
+        Notes:
+
+        1) If an input line begins with '!!', then %sx is automatically
+        invoked.  That is, while:
+          !ls
+        causes ipython to simply issue system('ls'), typing
+          !!ls
+        is a shorthand equivalent to:
+          %sx ls
+        
+        2) %sx differs from %sc in that %sx automatically splits into a list,
+        like '%sc -l'.  The reason for this is to make it as easy as possible
+        to process line-oriented shell output via further python commands.
+        %sc is meant to provide much finer control, but requires more
+        typing.
+
+        3) Just like %sc -l, this is a list with special attributes:
+
+          .l (or .list) : value as list.
+          .n (or .nlstr): value as newline-separated string.
+          .s (or .spstr): value as whitespace-separated string.
+
+        This is very useful when trying to use such lists as arguments to
+        system commands.
+
+**%system_verbose**::
+
+	Set verbose printing of system calls.
+
+        If called without an argument, act as a toggle
+
+**%time**::
+
+	Time execution of a Python statement or expression.
+
+        The CPU and wall clock times are printed, and the value of the
+        expression (if any) is returned.  Note that under Win32, system time
+        is always reported as 0, since it can not be measured.
+
+        This function provides very basic timing functionality.  In Python
+        2.3, the timeit module offers more control and sophistication, so this
+        could be rewritten to use it (patches welcome).
+        
+        Some examples:
+
+          In [1]: time 2**128
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00
+          Out[1]: 340282366920938463463374607431768211456L
+
+          In [2]: n = 1000000
+
+          In [3]: time sum(range(n))
+          CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
+          Wall time: 1.37
+          Out[3]: 499999500000L
+
+          In [4]: time print 'hello world'
+          hello world
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00
+
+          Note that the time needed by Python to compile the given expression
+          will be reported if it is more than 0.1s.  In this example, the
+          actual exponentiation is done by Python at compilation time, so while
+          the expression can take a noticeable amount of time to compute, that
+          time is purely due to the compilation:
+
+          In [5]: time 3**9999;
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00 s
+
+          In [6]: time 3**999999;
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00 s
+          Compiler : 0.78 s
+
+**%timeit**::
+
+	Time execution of a Python statement or expression
+
+        Usage:\
+          %timeit [-n<N> -r<R> [-t|-c]] statement
+
+        Time execution of a Python statement or expression using the timeit
+        module.
+
+        Options:
+        -n<N>: execute the given statement <N> times in a loop. If this value
+        is not given, a fitting value is chosen. 
+        
+        -r<R>: repeat the loop iteration <R> times and take the best result.
+        Default: 3
+        
+        -t: use time.time to measure the time, which is the default on Unix.
+        This function measures wall time.
+        
+        -c: use time.clock to measure the time, which is the default on
+        Windows and measures wall time. On Unix, resource.getrusage is used
+        instead and returns the CPU user time.
+
+        -p<P>: use a precision of <P> digits to display the timing result.
+        Default: 3
+
+        
+        Examples:\
+          In [1]: %timeit pass
+          10000000 loops, best of 3: 53.3 ns per loop
+
+          In [2]: u = None
+
+          In [3]: %timeit u is None
+          10000000 loops, best of 3: 184 ns per loop
+
+          In [4]: %timeit -r 4 u == None
+          1000000 loops, best of 4: 242 ns per loop
+
+          In [5]: import time
+
+          In [6]: %timeit -n1 time.sleep(2)
+          1 loops, best of 3: 2 s per loop
+          
+
+        The times reported by %timeit will be slightly higher than those
+        reported by the timeit.py script when variables are accessed. This is
+        due to the fact that %timeit executes the statement in the namespace
+        of the shell, compared with timeit.py, which uses a single setup
+        statement to import function or create variables. Generally, the bias
+        does not matter as long as results from timeit.py are not mixed with
+        those from %timeit.
+
+**%unalias**::
+
+	Remove an alias
+
+**%upgrade**::
+
+	 Upgrade your IPython installation
+        
+        This will copy the config files that don't yet exist in your 
+        ipython dir from the system config dir. Use this after upgrading 
+        IPython if you don't wish to delete your .ipython dir.
+
+        Call with -nolegacy to get rid of ipythonrc* files (recommended for
+        new users)
+
+**%which**::
+
+	 %which <cmd> => search PATH for files matching cmd. Also scans aliases.
+
+    Traverses PATH and prints all files (not just executables!) that match the
+    pattern on command line. Probably more useful in finding stuff
+    interactively than 'which', which only prints the first matching item.
+    
+    Also discovers and expands aliases, so you'll see what will be executed
+    when you call an alias.
+    
+    Example:
+    
+    [~]|62> %which d
+    d -> ls -F --color=auto
+      == c:\cygwin\bin\ls.exe
+    c:\cygwin\bin\d.exe
+    
+    [~]|64> %which diff*
+    diff3 -> diff3
+      == c:\cygwin\bin\diff3.exe
+    diff -> diff
+      == c:\cygwin\bin\diff.exe
+    c:\cygwin\bin\diff.exe
+    c:\cygwin\bin\diff3.exe
+
+**%who**::
+
+	Print all interactive variables, with some minimal formatting.
+
+        If any arguments are given, only variables whose type matches one of
+        these are printed.  For example:
+
+          %who function str
+
+        will only list functions and strings, excluding all other types of
+        variables.  To find the proper type names, simply use type(var) at a
+        command line to see how python prints type names.  For example:
+
+          In [1]: type('hello')\
+          Out[1]: <type 'str'>
+
+        indicates that the type name for strings is 'str'.
+
+        %who always excludes executed names loaded through your configuration
+        file and things which are internal to IPython.
+
+        This is deliberate, as typically you may load many modules and the
+        purpose of %who is to show you only what you've manually defined.
+
+**%who_ls**::
+
+	Return a sorted list of all interactive variables.
+
+        If arguments are given, only variables of types matching these
+        arguments are returned.
+
+**%whos**::
+
+	Like %who, but gives some extra information about each variable.
+
+        The same type filtering of %who can be applied here.
+
+        For all variables, the type is printed. Additionally it prints:
+        
+          - For {},[],(): their length.
+
+          - For numpy and Numeric arrays, a summary with shape, number of
+          elements, typecode and size in memory.
+
+          - Everything else: a string representation, snipping their middle if
+          too long.
+
+**%xmode**::
+
+	Switch modes for the exception handlers.
+
+        Valid modes: Plain, Context and Verbose.
+
+        If called without arguments, acts as a toggle.
+
+.. magic_end
+
+Access to the standard Python help
+----------------------------------
+
+As of Python 2.1, a help system is available with access to object
+docstrings and the Python manuals. Simply type 'help' (no quotes) to
+access it. You can also type help(object) to obtain information about a
+given object, and help('keyword') for information on a keyword. As noted
+in sec. `accessing help`_, you need to properly configure
+your environment variable PYTHONDOCS for this feature to work correctly.
+
+
+Dynamic object information
+--------------------------
+
+Typing ?word or word? prints detailed information about an object. If
+certain strings in the object are too long (docstrings, code, etc.) they
+get snipped in the center for brevity. This system gives access variable
+types and values, full source code for any object (if available),
+function prototypes and other useful information.
+
+Typing ??word or word?? gives access to the full information without
+snipping long strings. Long strings are sent to the screen through the
+less pager if longer than the screen and printed otherwise. On systems
+lacking the less command, IPython uses a very basic internal pager.
+
+The following magic functions are particularly useful for gathering
+information about your working environment. You can get more details by
+typing %magic or querying them individually (use %function_name? with or
+without the %), this is just a summary:
+
+    * **%pdoc <object>**: Print (or run through a pager if too long) the
+      docstring for an object. If the given object is a class, it will
+      print both the class and the constructor docstrings.
+    * **%pdef <object>**: Print the definition header for any callable
+      object. If the object is a class, print the constructor information.
+    * **%psource <object>**: Print (or run through a pager if too long)
+      the source code for an object.
+    * **%pfile <object>**: Show the entire source file where an object was
+      defined via a pager, opening it at the line where the object
+      definition begins.
+    * **%who/%whos**: These functions give information about identifiers
+      you have defined interactively (not things you loaded or defined
+      in your configuration files). %who just prints a list of
+      identifiers and %whos prints a table with some basic details about
+      each identifier.
+
+Note that the dynamic object information functions (?/??, %pdoc, %pfile,
+%pdef, %psource) give you access to documentation even on things which
+are not really defined as separate identifiers. Try for example typing
+{}.get? or after doing import os, type os.path.abspath??.
+
+
+.. _Readline:
+
+Readline-based features
+-----------------------
+
+These features require the GNU readline library, so they won't work if
+your Python installation lacks readline support. We will first describe
+the default behavior IPython uses, and then how to change it to suit
+your preferences.
+
+
+Command line completion
++++++++++++++++++++++++
+
+At any time, hitting TAB will complete any available python commands or
+variable names, and show you a list of the possible completions if
+there's no unambiguous one. It will also complete filenames in the
+current directory if no python names match what you've typed so far.
+
+
+Search command history
+++++++++++++++++++++++
+
+IPython provides two ways for searching through previous input and thus
+reduce the need for repetitive typing:
+
+   1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
+      (next,down) to search through only the history items that match
+      what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
+      prompt, they just behave like normal arrow keys.
+   2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
+      searches your history for lines that contain what you've typed so
+      far, completing as much as it can.
+
+
+Persistent command history across sessions
+++++++++++++++++++++++++++++++++++++++++++
+
+IPython will save your input history when it leaves and reload it next
+time you restart it. By default, the history file is named
+$IPYTHONDIR/history, but if you've loaded a named profile,
+'-PROFILE_NAME' is appended to the name. This allows you to keep
+separate histories related to various tasks: commands related to
+numerical work will not be clobbered by a system shell history, for
+example.
+
+
+Autoindent
+++++++++++
+
+IPython can recognize lines ending in ':' and indent the next line,
+while also un-indenting automatically after 'raise' or 'return'.
+
+This feature uses the readline library, so it will honor your ~/.inputrc
+configuration (or whatever file your INPUTRC variable points to). Adding
+the following lines to your .inputrc file can make indenting/unindenting
+more convenient (M-i indents, M-u unindents)::
+
+    $if Python 
+    "\M-i": "    "  
+    "\M-u": "\d\d\d\d"  
+    $endif
+
+Note that there are 4 spaces between the quote marks after "M-i" above.
+
+Warning: this feature is ON by default, but it can cause problems with
+the pasting of multi-line indented code (the pasted code gets
+re-indented on each line). A magic function %autoindent allows you to
+toggle it on/off at runtime. You can also disable it permanently on in
+your ipythonrc file (set autoindent 0).
+
+
+Customizing readline behavior
++++++++++++++++++++++++++++++
+
+All these features are based on the GNU readline library, which has an
+extremely customizable interface. Normally, readline is configured via a
+file which defines the behavior of the library; the details of the
+syntax for this can be found in the readline documentation available
+with your system or on the Internet. IPython doesn't read this file (if
+it exists) directly, but it does support passing to readline valid
+options via a simple interface. In brief, you can customize readline by
+setting the following options in your ipythonrc configuration file (note
+that these options can not be specified at the command line):
+
+    * **readline_parse_and_bind**: this option can appear as many times as
+      you want, each time defining a string to be executed via a
+      readline.parse_and_bind() command. The syntax for valid commands
+      of this kind can be found by reading the documentation for the GNU
+      readline library, as these commands are of the kind which readline
+      accepts in its configuration file.
+    * **readline_remove_delims**: a string of characters to be removed
+      from the default word-delimiters list used by readline, so that
+      completions may be performed on strings which contain them. Do not
+      change the default value unless you know what you're doing.
+    * **readline_omit__names**: when tab-completion is enabled, hitting
+      <tab> after a '.' in a name will complete all attributes of an
+      object, including all the special methods whose names include
+      double underscores (like __getitem__ or __class__). If you'd
+      rather not see these names by default, you can set this option to
+      1. Note that even when this option is set, you can still see those
+      names by explicitly typing a _ after the period and hitting <tab>:
+      'name._<tab>' will always complete attribute names starting with '_'.
+      
+      This option is off by default so that new users see all
+      attributes of any objects they are dealing with.
+
+You will find the default values along with a corresponding detailed
+explanation in your ipythonrc file.
+
+
+Session logging and restoring
+-----------------------------
+
+You can log all input from a session either by starting IPython with
+the command line switches -log or -logfile (see sec. `command line
+options`_) or by activating the logging at any moment with the magic
+function %logstart.
+
+Log files can later be reloaded with the -logplay option and IPython
+will attempt to 'replay' the log by executing all the lines in it, thus
+restoring the state of a previous session. This feature is not quite
+perfect, but can still be useful in many cases.
+
+The log files can also be used as a way to have a permanent record of
+any code you wrote while experimenting. Log files are regular text files
+which you can later open in your favorite text editor to extract code or
+to 'clean them up' before using them to replay a session.
+
+The %logstart function for activating logging in mid-session is used as
+follows:
+
+%logstart [log_name [log_mode]]
+
+If no name is given, it defaults to a file named 'log' in your
+IPYTHONDIR directory, in 'rotate' mode (see below).
+
+'%logstart name' saves to file 'name' in 'backup' mode. It saves your
+history up to that point and then continues logging.
+
+%logstart takes a second optional parameter: logging mode. This can be
+one of (note that the modes are given unquoted):
+
+    * [over:] overwrite existing log_name.
+    * [backup:] rename (if exists) to log_name~ and start log_name.
+    * [append:] well, that says it.
+    * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
+
+The %logoff and %logon functions allow you to temporarily stop and
+resume logging to a file which had previously been started with
+%logstart. They will fail (with an explanation) if you try to use them
+before logging has been started.
+
+System shell access
+-------------------
+
+Any input line beginning with a ! character is passed verbatim (minus
+the !, of course) to the underlying operating system. For example,
+typing !ls will run 'ls' in the current directory.
+
+Manual capture of command output
+--------------------------------
+
+If the input line begins with two exclamation marks, !!, the command is
+executed but its output is captured and returned as a python list, split
+on newlines. Any output sent by the subprocess to standard error is
+printed separately, so that the resulting list only captures standard
+output. The !! syntax is a shorthand for the %sx magic command.
+
+Finally, the %sc magic (short for 'shell capture') is similar to %sx,
+but allowing more fine-grained control of the capture details, and
+storing the result directly into a named variable. The direct use of 
+%sc is now deprecated, and you should ise the ``var = !cmd`` syntax
+instead.
+
+IPython also allows you to expand the value of python variables when
+making system calls. Any python variable or expression which you prepend
+with $ will get expanded before the system call is made::
+
+    In [1]: pyvar='Hello world' 
+    In [2]: !echo "A python variable: $pyvar"  
+    A python variable: Hello world
+
+If you want the shell to actually see a literal $, you need to type it
+twice::
+
+    In [3]: !echo "A system variable: $$HOME"  
+    A system variable: /home/fperez
+
+You can pass arbitrary expressions, though you'll need to delimit them
+with {} if there is ambiguity as to the extent of the expression::
+
+    In [5]: x=10 
+    In [6]: y=20 
+    In [13]: !echo $x+y  
+    10+y  
+    In [7]: !echo ${x+y}  
+    30
+
+Even object attributes can be expanded::
+
+    In [12]: !echo $sys.argv  
+    [/home/fperez/usr/bin/ipython]
+
+
+System command aliases
+----------------------
+
+The %alias magic function and the alias option in the ipythonrc
+configuration file allow you to define magic functions which are in fact
+system shell commands. These aliases can have parameters.
+
+'%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
+
+Then, typing '%alias_name params' will execute the system command 'cmd
+params' (from your underlying operating system).
+
+You can also define aliases with parameters using %s specifiers (one per
+parameter). The following example defines the %parts function as an
+alias to the command 'echo first %s second %s' where each %s will be
+replaced by a positional parameter to the call to %parts::
+
+    In [1]: alias parts echo first %s second %s 
+    In [2]: %parts A B 
+    first A second B  
+    In [3]: %parts A  
+    Incorrect number of arguments: 2 expected.  
+    parts is an alias to: 'echo first %s second %s'
+
+If called with no parameters, %alias prints the table of currently
+defined aliases.
+
+The %rehash/rehashx magics allow you to load your entire $PATH as
+ipython aliases. See their respective docstrings (or sec. 6.2
+<#sec:magic> for further details).
+
+
+.. _dreload:
+
+Recursive reload
+----------------
+
+The dreload function does a recursive reload of a module: changes made
+to the module since you imported will actually be available without
+having to exit.
+
+
+Verbose and colored exception traceback printouts
+-------------------------------------------------
+
+IPython provides the option to see very detailed exception tracebacks,
+which can be especially useful when debugging large programs. You can
+run any Python file with the %run function to benefit from these
+detailed tracebacks. Furthermore, both normal and verbose tracebacks can
+be colored (if your terminal supports it) which makes them much easier
+to parse visually.
+
+See the magic xmode and colors functions for details (just type %magic).
+
+These features are basically a terminal version of Ka-Ping Yee's cgitb
+module, now part of the standard Python library.
+
+
+.. _Input caching:
+
+Input caching system
+--------------------
+
+IPython offers numbered prompts (In/Out) with input and output caching.
+All input is saved and can be retrieved as variables (besides the usual
+arrow key recall).
+
+The following GLOBAL variables always exist (so don't overwrite them!):
+_i: stores previous input. _ii: next previous. _iii: next-next previous.
+_ih : a list of all input _ih[n] is the input from line n and this list
+is aliased to the global variable In. If you overwrite In with a
+variable of your own, you can remake the assignment to the internal list
+with a simple 'In=_ih'.
+
+Additionally, global variables named _i<n> are dynamically created (<n>
+being the prompt counter), such that
+_i<n> == _ih[<n>] == In[<n>].
+
+For example, what you typed at prompt 14 is available as _i14, _ih[14]
+and In[14].
+
+This allows you to easily cut and paste multi line interactive prompts
+by printing them out: they print like a clean string, without prompt
+characters. You can also manipulate them like regular variables (they
+are strings), modify or exec them (typing 'exec _i9' will re-execute the
+contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
+9 through 13 and line 18).
+
+You can also re-execute multiple lines of input easily by using the
+magic %macro function (which automates the process and allows
+re-execution without having to type 'exec' every time). The macro system
+also allows you to re-execute previous lines which include magic
+function calls (which require special processing). Type %macro? or see
+sec. 6.2 <#sec:magic> for more details on the macro system.
+
+A history function %hist allows you to see any part of your input
+history by printing a range of the _i variables.
+
+.. _Output caching:
+
+Output caching system
+---------------------
+
+For output that is returned from actions, a system similar to the input
+cache exists but using _ instead of _i. Only actions that produce a
+result (NOT assignments, for example) are cached. If you are familiar
+with Mathematica, IPython's _ variables behave exactly like
+Mathematica's % variables.
+
+The following GLOBAL variables always exist (so don't overwrite them!):
+
+    * [_] (a single underscore) : stores previous output, like Python's
+      default interpreter.
+    * [__] (two underscores): next previous.
+    * [___] (three underscores): next-next previous.
+
+Additionally, global variables named _<n> are dynamically created (<n>
+being the prompt counter), such that the result of output <n> is always
+available as _<n> (don't use the angle brackets, just the number, e.g.
+_21).
+
+These global variables are all stored in a global dictionary (not a
+list, since it only has entries for lines which returned a result)
+available under the names _oh and Out (similar to _ih and In). So the
+output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
+accidentally overwrite the Out variable you can recover it by typing
+'Out=_oh' at the prompt.
+
+This system obviously can potentially put heavy memory demands on your
+system, since it prevents Python's garbage collector from removing any
+previously computed results. You can control how many results are kept
+in memory with the option (at the command line or in your ipythonrc
+file) cache_size. If you set it to 0, the whole system is completely
+disabled and the prompts revert to the classic '>>>' of normal Python.
+
+
+Directory history
+-----------------
+
+Your history of visited directories is kept in the global list _dh, and
+the magic %cd command can be used to go to any entry in that list. The
+%dhist command allows you to view this history. do ``cd -<TAB`` to
+conventiently view the directory history.
+
+
+Automatic parentheses and quotes
+--------------------------------
+
+These features were adapted from Nathan Gray's LazyPython. They are
+meant to allow less typing for common situations.
+
+
+Automatic parentheses
+---------------------
+
+Callable objects (i.e. functions, methods, etc) can be invoked like this
+(notice the commas between the arguments)::
+
+    >>> callable_ob arg1, arg2, arg3
+
+and the input will be translated to this::
+
+    -> callable_ob(arg1, arg2, arg3)
+
+You can force automatic parentheses by using '/' as the first character
+of a line. For example::
+
+    >>> /globals # becomes 'globals()'
+
+Note that the '/' MUST be the first character on the line! This won't work::
+
+    >>> print /globals # syntax error
+
+In most cases the automatic algorithm should work, so you should rarely
+need to explicitly invoke /. One notable exception is if you are trying
+to call a function with a list of tuples as arguments (the parenthesis
+will confuse IPython)::
+
+    In [1]: zip (1,2,3),(4,5,6) # won't work
+
+but this will work::
+
+    In [2]: /zip (1,2,3),(4,5,6) 
+    ---> zip ((1,2,3),(4,5,6))  
+    Out[2]= [(1, 4), (2, 5), (3, 6)]
+
+IPython tells you that it has altered your command line by displaying
+the new command line preceded by ->. e.g.::
+
+    In [18]: callable list 
+    ----> callable (list)
+
+
+Automatic quoting
+-----------------
+
+You can force automatic quoting of a function's arguments by using ','
+or ';' as the first character of a line. For example::
+
+    >>> ,my_function /home/me # becomes my_function("/home/me")
+
+If you use ';' instead, the whole argument is quoted as a single string
+(while ',' splits on whitespace)::
+
+    >>> ,my_function a b c # becomes my_function("a","b","c")
+
+    >>> ;my_function a b c # becomes my_function("a b c")
+
+Note that the ',' or ';' MUST be the first character on the line! This
+won't work::
+
+    >>> x = ,my_function /home/me # syntax error
+
+.. customization:
+
+Customization
+=============
+
+There are 2 ways to configure IPython - the old way of using ipythonrc
+files (an INI-file like format), and the new way that involves editing
+your ipy_user_conf.py. Both configuration systems work at the same
+time, so you can set your options in both, but if you are hesitating
+about which alternative to choose, we recommend the ipy_user_conf.py
+approach, as it will give you more power and control in the long
+run. However, there are few options such as pylab_import_all that can
+only be specified in ipythonrc file or command line - the reason for
+this is that they are needed before IPython has been started up, and
+the IPApi object used in ipy_user_conf.py is not yet available at that
+time. A hybrid approach of specifying a few options in ipythonrc and
+doing the more advanced configuration in ipy_user_conf.py is also
+possible.
+
+The ipythonrc approach
+----------------------
+
+As we've already mentioned, IPython reads a configuration file which can
+be specified at the command line (-rcfile) or which by default is
+assumed to be called ipythonrc. Such a file is looked for in the current
+directory where IPython is started and then in your IPYTHONDIR, which
+allows you to have local configuration files for specific projects. In
+this section we will call these types of configuration files simply
+rcfiles (short for resource configuration file).
+
+The syntax of an rcfile is one of key-value pairs separated by
+whitespace, one per line. Lines beginning with a # are ignored as
+comments, but comments can not be put on lines with data (the parser is
+fairly primitive). Note that these are not python files, and this is
+deliberate, because it allows us to do some things which would be quite
+tricky to implement if they were normal python files.
+
+First, an rcfile can contain permanent default values for almost all
+command line options (except things like -help or -Version). Sec
+`command line options`_ contains a description of all command-line
+options. However, values you explicitly specify at the command line
+override the values defined in the rcfile.
+
+Besides command line option values, the rcfile can specify values for
+certain extra special options which are not available at the command
+line. These options are briefly described below.
+
+Each of these options may appear as many times as you need it in the file.
+
+    * include <file1> <file2> ...: you can name other rcfiles you want
+      to recursively load up to 15 levels (don't use the <> brackets in
+      your names!). This feature allows you to define a 'base' rcfile
+      with general options and special-purpose files which can be loaded
+      only when needed with particular configuration options. To make
+      this more convenient, IPython accepts the -profile <name> option
+      (abbreviates to -p <name>) which tells it to look for an rcfile
+      named ipythonrc-<name>.
+    * import_mod <mod1> <mod2> ...: import modules with 'import
+      <mod1>,<mod2>,...'
+    * import_some <mod> <f1> <f2> ...: import functions with 'from
+      <mod> import <f1>,<f2>,...'
+    * import_all <mod1> <mod2> ...: for each module listed import
+      functions with ``from <mod> import *``.
+    * execute <python code>: give any single-line python code to be
+      executed.
+    * execfile <filename>: execute the python file given with an
+      'execfile(filename)' command. Username expansion is performed on
+      the given names. So if you need any amount of extra fancy
+      customization that won't fit in any of the above 'canned' options,
+      you can just put it in a separate python file and execute it.
+    * alias <alias_def>: this is equivalent to calling
+      '%alias <alias_def>' at the IPython command line. This way, from
+      within IPython you can do common system tasks without having to
+      exit it or use the ! escape. IPython isn't meant to be a shell
+      replacement, but it is often very useful to be able to do things
+      with files while testing code. This gives you the flexibility to
+      have within IPython any aliases you may be used to under your
+      normal system shell.
+
+
+.. _ipythonrc:
+
+Sample ipythonrc file
+---------------------
+
+The default rcfile, called ipythonrc and supplied in your IPYTHONDIR
+directory contains lots of comments on all of these options. We
+reproduce it here for reference::
+
+
+    # -*- Mode: Shell-Script -*-  Not really, but shows comments correctly
+    # $Id: ipythonrc 2156 2007-03-19 02:32:19Z fperez $
+
+    #***************************************************************************
+    #
+    # Configuration file for IPython -- ipythonrc format
+    #
+    # ===========================================================
+    # Deprecation note: you should look into modifying ipy_user_conf.py (located 
+    # in ~/.ipython or ~/_ipython, depending on your platform) instead, it's a 
+    # more flexible and robust (and better supported!) configuration
+    # method.
+    # ===========================================================
+    #
+    # The format of this file is simply one of 'key value' lines.
+    # Lines containing only whitespace at the beginning and then a # are ignored
+    # as comments. But comments can NOT be put on lines with data.
+
+    # The meaning and use of each key are explained below.
+
+    #---------------------------------------------------------------------------
+    # Section: included files
+
+    # Put one or more *config* files (with the syntax of this file) you want to
+    # include. For keys with a unique value the outermost file has precedence. For
+    # keys with multiple values, they all get assembled into a list which then
+    # gets loaded by IPython.
+
+    # In this file, all lists of things should simply be space-separated.
+
+    # This allows you to build hierarchies of files which recursively load
+    # lower-level services. If this is your main ~/.ipython/ipythonrc file, you
+    # should only keep here basic things you always want available. Then you can
+    # include it in every other special-purpose config file you create.
+    include 
+
+    #---------------------------------------------------------------------------
+    # Section: startup setup
+
+    # These are mostly things which parallel a command line option of the same
+    # name.
+
+    # Keys in this section should only appear once. If any key from this section
+    # is encountered more than once, the last value remains, all earlier ones get
+    # discarded.
+
+
+    # Automatic calling of callable objects.  If set to 1 or 2, callable objects
+    # are automatically called when invoked at the command line, even if you don't
+    # type parentheses.  IPython adds the parentheses for you.  For example:
+
+    #In [1]: str 45
+    #------> str(45)
+    #Out[1]: '45'
+
+    # IPython reprints your line with '---->' indicating that it added
+    # parentheses.  While this option is very convenient for interactive use, it
+    # may occasionally cause problems with objects which have side-effects if
+    # called unexpectedly.
+
+    # The valid values for autocall are:
+
+    # autocall 0 -> disabled (you can toggle it at runtime with the %autocall magic)
+
+    # autocall 1 -> active, but do not apply if there are no arguments on the line.
+
+    # In this mode, you get:
+
+    #In [1]: callable
+    #Out[1]: <built-in function callable>
+
+    #In [2]: callable 'hello'
+    #------> callable('hello')
+    #Out[2]: False
+
+    # 2 -> Active always.  Even if no arguments are present, the callable object
+    # is called:
+
+    #In [4]: callable
+    #------> callable()
+
+    # Note that even with autocall off, you can still use '/' at the start of a
+    # line to treat the first argument on the command line as a function and add
+    # parentheses to it:
+
+    #In [8]: /str 43
+    #------> str(43)
+    #Out[8]: '43'
+
+    autocall 1
+
+    # Auto-edit syntax errors.  When you use the %edit magic in ipython to edit
+    # source code (see the 'editor' variable below), it is possible that you save
+    # a file with syntax errors in it.  If this variable is true, IPython will ask
+    # you whether to re-open the editor immediately to correct such an error.
+
+    autoedit_syntax 0
+
+    # Auto-indent. IPython can recognize lines ending in ':' and indent the next
+    # line, while also un-indenting automatically after 'raise' or 'return'.  
+
+    # This feature uses the readline library, so it will honor your ~/.inputrc
+    # configuration (or whatever file your INPUTRC variable points to).  Adding
+    # the following lines to your .inputrc file can make indent/unindenting more
+    # convenient (M-i indents, M-u unindents):
+
+    #  $if Python
+    #  "\M-i": "    "
+    #  "\M-u": "\d\d\d\d"
+    #  $endif
+
+    # The feature is potentially a bit dangerous, because it can cause problems
+    # with pasting of indented code (the pasted code gets re-indented on each
+    # line).  But it's a huge time-saver when working interactively.  The magic
+    # function %autoindent allows you to toggle it on/off at runtime.
+
+    autoindent 1
+
+    # Auto-magic. This gives you access to all the magic functions without having
+    # to prepend them with an % sign. If you define a variable with the same name
+    # as a magic function (say who=1), you will need to access the magic function
+    # with % (%who in this example). However, if later you delete your variable
+    # (del who), you'll recover the automagic calling form.
+
+    # Considering that many magic functions provide a lot of shell-like
+    # functionality, automagic gives you something close to a full Python+system
+    # shell environment (and you can extend it further if you want).
+
+    automagic 1
+
+    # Size of the output cache. After this many entries are stored, the cache will
+    # get flushed. Depending on the size of your intermediate calculations, you
+    # may have memory problems if you make it too big, since keeping things in the
+    # cache prevents Python from reclaiming the memory for old results. Experiment
+    # with a value that works well for you.
+
+    # If you choose cache_size 0 IPython will revert to python's regular >>>
+    # unnumbered prompt. You will still have _, __ and ___ for your last three
+    # results, but that will be it.  No dynamic _1, _2, etc. will be created. If
+    # you are running on a slow machine or with very limited memory, this may
+    # help.
+
+    cache_size 1000
+
+    # Classic mode: Setting 'classic 1' you lose many of IPython niceties,
+    # but that's your choice! Classic 1 -> same as IPython -classic.
+    # Note that this is _not_ the normal python interpreter, it's simply
+    # IPython emulating most of the classic interpreter's behavior.
+    classic 0
+
+    # colors - Coloring option for prompts and traceback printouts.
+
+    # Currently available schemes: NoColor, Linux, LightBG.
+
+    # This option allows coloring the prompts and traceback printouts. This
+    # requires a terminal which can properly handle color escape sequences. If you
+    # are having problems with this, use the NoColor scheme (uses no color escapes
+    # at all).
+
+    # The Linux option works well in linux console type environments: dark
+    # background with light fonts.
+
+    # LightBG is similar to Linux but swaps dark/light colors to be more readable
+    # in light background terminals.
+
+    # keep uncommented only the one you want:
+    colors Linux
+    #colors LightBG
+    #colors NoColor
+
+    ########################
+    # Note to Windows users
+    #
+    # Color and readline support is avaialble to Windows users via Gary Bishop's
+    # readline library.  You can find Gary's tools at
+    # http://sourceforge.net/projects/uncpythontools.
+    # Note that his readline module requires in turn the ctypes library, available
+    # at http://starship.python.net/crew/theller/ctypes.
+    ########################
+
+    # color_info: IPython can display information about objects via a set of
+    # functions, and optionally can use colors for this, syntax highlighting
+    # source code and various other elements. This information is passed through a
+    # pager (it defaults to 'less' if $PAGER is not set). 
+
+    # If your pager has problems, try to setting it to properly handle escapes
+    # (see the less manpage for detail), or disable this option.  The magic
+    # function %color_info allows you to toggle this interactively for testing.
+
+    color_info 1
+
+    # confirm_exit: set to 1 if you want IPython to confirm when you try to exit
+    # with an EOF (Control-d in Unix, Control-Z/Enter in Windows). Note that using
+    # the magic functions %Exit or %Quit you can force a direct exit, bypassing
+    # any confirmation.
+
+    confirm_exit 1
+
+    # Use deep_reload() as a substitute for reload() by default. deep_reload() is
+    # still available as dreload() and appears as a builtin.
+
+    deep_reload 0
+
+    # Which editor to use with the %edit command. If you leave this at 0, IPython
+    # will honor your EDITOR environment variable. Since this editor is invoked on
+    # the fly by ipython and is meant for editing small code snippets, you may
+    # want to use a small, lightweight editor here.
+
+    # For Emacs users, setting up your Emacs server properly as described in the
+    # manual is a good idea. An alternative is to use jed, a very light editor
+    # with much of the feel of Emacs (though not as powerful for heavy-duty work).
+
+    editor 0
+
+    # log 1 -> same as ipython -log. This automatically logs to ./ipython.log
+    log 0
+
+    # Same as ipython -Logfile YourLogfileName. 
+    # Don't use with log 1 (use one or the other)
+    logfile ''
+
+    # banner 0 -> same as ipython -nobanner
+    banner 1
+
+    # messages 0 -> same as ipython -nomessages
+    messages 1
+
+    # Automatically call the pdb debugger after every uncaught exception. If you
+    # are used to debugging using pdb, this puts you automatically inside of it
+    # after any call (either in IPython or in code called by it) which triggers an
+    # exception which goes uncaught.
+    pdb 0
+
+    # Enable the pprint module for printing. pprint tends to give a more readable
+    # display (than print) for complex nested data structures.
+    pprint 1
+
+    # Prompt strings
+
+    # Most bash-like escapes can be used to customize IPython's prompts, as well as
+    # a few additional ones which are IPython-specific.  All valid prompt escapes
+    # are described in detail in the Customization section of the IPython HTML/PDF
+    # manual.
+
+    # Use \# to represent the current prompt number, and quote them to protect
+    # spaces.
+    prompt_in1 'In [\#]: '
+
+    # \D is replaced by as many dots as there are digits in the
+    # current value of \#.
+    prompt_in2 '   .\D.: '
+
+    prompt_out 'Out[\#]: '
+
+    # Select whether to left-pad the output prompts to match the length of the
+    # input ones.  This allows you for example to use a simple '>' as an output
+    # prompt, and yet have the output line up with the input.  If set to false,
+    # the output prompts will be unpadded (flush left).
+    prompts_pad_left 1
+
+    # Pylab support: when ipython is started with the -pylab switch, by default it
+    # executes 'from matplotlib.pylab import *'.  Set this variable to false if you
+    # want to disable this behavior.
+
+    # For details on pylab, see the matplotlib website:
+    # http://matplotlib.sf.net
+    pylab_import_all 1
+
+
+    # quick 1 -> same as ipython -quick
+    quick 0
+
+    # Use the readline library (1) or not (0). Most users will want this on, but
+    # if you experience strange problems with line management (mainly when using
+    # IPython inside Emacs buffers) you may try disabling it. Not having it on
+    # prevents you from getting command history with the arrow keys, searching and
+    # name completion using TAB.
+
+    readline 1
+
+    # Screen Length: number of lines of your screen. This is used to control
+    # printing of very long strings. Strings longer than this number of lines will
+    # be paged with the less command 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. If for some reason this isn't
+    # working well (it needs curses support), specify it yourself. Otherwise don't
+    # change the default.
+
+    screen_length 0
+
+    # Prompt separators for input and output.
+    # Use \n for newline explicitly, without quotes.
+    # Use 0 (like at the cmd line) to turn off a given separator.
+
+    # The structure of prompt printing is:
+    # (SeparateIn)Input....
+    # (SeparateOut)Output...
+    # (SeparateOut2),   # that is, no newline is printed after Out2
+    # By choosing these you can organize your output any way you want.
+
+    separate_in \n
+    separate_out 0
+    separate_out2 0
+
+    # 'nosep 1' is a shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'.
+    # Simply removes all input/output separators, overriding the choices above.
+    nosep 0
+
+    # Wildcard searches - IPython has a system for searching names using
+    # shell-like wildcards; type %psearch? for details.  This variables sets
+    # whether by default such searches should be case sensitive or not.  You can
+    # always override the default at the system command line or the IPython
+    # prompt.
+
+    wildcards_case_sensitive 1
+
+    # Object information: at what level of detail to display the string form of an
+    # object.  If set to 0, ipython will compute the string form of any object X,
+    # by calling str(X), when X? is typed.  If set to 1, str(X) will only be
+    # computed when X?? is given, and if set to 2 or higher, it will never be
+    # computed (there is no X??? level of detail).  This is mostly of use to
+    # people who frequently manipulate objects whose string representation is
+    # extremely expensive to compute.
+
+    object_info_string_level 0
+
+    # xmode - Exception reporting mode. 
+
+    # Valid modes: Plain, Context and Verbose.
+
+    # Plain: similar to python's normal traceback printing.
+
+    # Context: prints 5 lines of context source code around each line in the
+    # traceback.
+
+    # Verbose: similar to Context, but additionally prints the variables currently
+    # visible where the exception happened (shortening their strings if too
+    # long). This can potentially be very slow, if you happen to have a huge data
+    # structure whose string representation is complex to compute. Your computer
+    # may appear to freeze for a while with cpu usage at 100%. If this occurs, you
+    # can cancel the traceback with Ctrl-C (maybe hitting it more than once).
+
+    #xmode Plain
+    xmode Context
+    #xmode Verbose
+
+    # multi_line_specials: if true, allow magics, aliases and shell escapes (via
+    # !cmd) to be used in multi-line input (like for loops).  For example, if you
+    # have this active, the following is valid in IPython:
+    #
+    #In [17]: for i in range(3):
+    #   ....:     mkdir $i
+    #   ....:     !touch $i/hello
+    #   ....:     ls -l $i
+
+    multi_line_specials 1
+
+
+    # System calls: When IPython makes system calls (e.g. via special syntax like
+    # !cmd or !!cmd, or magics like %sc or %sx), it can print the command it is
+    # executing to standard output, prefixed by a header string.
+
+    system_header "IPython system call: "
+
+    system_verbose 1
+
+    # wxversion: request a specific wxPython version (used for -wthread)
+
+    # Set this to the value of wxPython you want to use, but note that this
+    # feature requires you to have the wxversion Python module to work.  If you
+    # don't have the wxversion module (try 'import wxversion' at the prompt to
+    # check) or simply want to leave the system to pick up the default, leave this
+    # variable at 0.
+
+    wxversion 0
+
+    #---------------------------------------------------------------------------
+    # Section: Readline configuration (readline is not available for MS-Windows)
+
+    # This is done via the following options:
+
+    # (i) readline_parse_and_bind: this option can appear as many times as you
+    # want, each time defining a string to be executed via a
+    # readline.parse_and_bind() command. The syntax for valid commands of this
+    # kind can be found by reading the documentation for the GNU readline library,
+    # as these commands are of the kind which readline accepts in its
+    # configuration file.
+
+    # The TAB key can be used to complete names at the command line in one of two
+    # ways: 'complete' and 'menu-complete'. The difference is that 'complete' only
+    # completes as much as possible while 'menu-complete' cycles through all
+    # possible completions. Leave the one you prefer uncommented.
+
+    readline_parse_and_bind tab: complete
+    #readline_parse_and_bind tab: menu-complete
+
+    # This binds Control-l to printing the list of all possible completions when
+    # there is more than one (what 'complete' does when hitting TAB twice, or at
+    # the first TAB if show-all-if-ambiguous is on)
+    readline_parse_and_bind "\C-l": possible-completions
+
+    # This forces readline to automatically print the above list when tab
+    # completion is set to 'complete'. You can still get this list manually by
+    # using the key bound to 'possible-completions' (Control-l by default) or by
+    # hitting TAB twice. Turning this on makes the printing happen at the first
+    # TAB.
+    readline_parse_and_bind set show-all-if-ambiguous on
+
+    # If you have TAB set to complete names, you can rebind any key (Control-o by
+    # default) to insert a true TAB character.
+    readline_parse_and_bind "\C-o": tab-insert
+
+    # These commands allow you to indent/unindent easily, with the 4-space
+    # convention of the Python coding standards.  Since IPython's internal
+    # auto-indent system also uses 4 spaces, you should not change the number of
+    # spaces in the code below.
+    readline_parse_and_bind "\M-i": "    "
+    readline_parse_and_bind "\M-o": "\d\d\d\d"
+    readline_parse_and_bind "\M-I": "\d\d\d\d"
+
+    # Bindings for incremental searches in the history. These searches use the
+    # string typed so far on the command line and search anything in the previous
+    # input history containing them.
+    readline_parse_and_bind "\C-r": reverse-search-history
+    readline_parse_and_bind "\C-s": forward-search-history
+
+    # Bindings for completing the current line in the history of previous
+    # commands. This allows you to recall any previous command by typing its first
+    # few letters and hitting Control-p, bypassing all intermediate commands which
+    # may be in the history (much faster than hitting up-arrow 50 times!)
+    readline_parse_and_bind "\C-p": history-search-backward
+    readline_parse_and_bind "\C-n": history-search-forward
+
+    # I also like to have the same functionality on the plain arrow keys. If you'd
+    # rather have the arrows use all the history (and not just match what you've
+    # typed so far), comment out or delete the next two lines.
+    readline_parse_and_bind "\e[A": history-search-backward
+    readline_parse_and_bind "\e[B": history-search-forward
+
+    # These are typically on by default under *nix, but not win32.
+    readline_parse_and_bind "\C-k": kill-line
+    readline_parse_and_bind "\C-u": unix-line-discard
+
+    # (ii) 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.
+
+    readline_remove_delims -/~
+
+    # (iii) readline_merge_completions: whether to merge the result of all
+    # possible completions or not.  If true, IPython will complete filenames,
+    # python names and aliases and return all possible completions.  If you set it
+    # to false, each completer is used at a time, and only if it doesn't return
+    # any completions is the next one used.
+
+    # The default order is: [python_matches, file_matches, alias_matches]
+
+    readline_merge_completions 1
+
+    # (iv) readline_omit__names: normally hitting <tab> after a '.' in a name
+    # will complete all attributes of an object, including all the special methods
+    # whose names start with single or double underscores (like __getitem__ or
+    # __class__).
+
+    # This variable allows you to control this completion behavior:
+
+    # readline_omit__names 1 -> completion will omit showing any names starting
+    # with two __, but it will still show names starting with one _.
+
+    # readline_omit__names 2 -> completion will omit all names beginning with one
+    # _ (which obviously means filtering out the double __ ones).
+
+    # Even when this option is set, you can still see those names by explicitly
+    # typing a _ after the period and hitting <tab>: 'name._<tab>' will always
+    # complete attribute names starting with '_'.
+
+    # This option is off by default so that new users see all attributes of any
+    # objects they are dealing with.
+
+    readline_omit__names 0
+
+    #---------------------------------------------------------------------------
+    # Section: modules to be loaded with 'import ...'
+
+    # List, separated by spaces, the names of the modules you want to import
+
+    # Example:
+    # import_mod sys os
+    # will produce internally the statements
+    # import sys
+    # import os
+
+    # Each import is executed in its own try/except block, so if one module
+    # fails to load the others will still be ok.
+
+    import_mod 
+
+    #---------------------------------------------------------------------------
+    # Section: modules to import some functions from: 'from ... import ...'
+
+    # List, one per line, the modules for which you want only to import some
+    # functions. Give the module name first and then the name of functions to be
+    # imported from that module.
+
+    # Example:
+
+    # import_some IPython.genutils timing timings
+    # will produce internally the statement
+    # from IPython.genutils import timing, timings
+
+    # timing() and timings() are two IPython utilities for timing the execution of
+    # your own functions, which you may find useful.  Just commment out the above
+    # line if you want to test them.
+
+    # If you have more than one modules_some line, each gets its own try/except
+    # block (like modules, see above).
+
+    import_some 
+
+    #---------------------------------------------------------------------------
+    # Section: modules to import all from : 'from ... import *'
+
+    # List (same syntax as import_mod above) those modules for which you want to
+    # import all functions. Remember, this is a potentially dangerous thing to do,
+    # since it is very easy to overwrite names of things you need. Use with
+    # caution.
+
+    # Example:
+    # import_all sys os
+    # will produce internally the statements
+    # from sys import *
+    # from os import *
+
+    # As before, each will be called in a separate try/except block.
+
+    import_all 
+
+    #---------------------------------------------------------------------------
+    # Section: Python code to execute.
+
+    # Put here code to be explicitly executed (keep it simple!)
+    # Put one line of python code per line. All whitespace is removed (this is a
+    # feature, not a bug), so don't get fancy building loops here.
+    # This is just for quick convenient creation of things you want available.
+
+    # Example:
+    # execute x = 1
+    # execute print 'hello world'; y = z = 'a'
+    # will produce internally
+    # x = 1
+    # print 'hello world'; y = z = 'a'
+    # and each *line* (not each statement, we don't do python syntax parsing) is
+    # executed in its own try/except block.
+
+    execute 
+
+    # Note for the adventurous: you can use this to define your own names for the
+    # magic functions, by playing some namespace tricks:
+
+    # execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
+
+    # defines %pf as a new name for %profile.
+
+    #---------------------------------------------------------------------------
+    # Section: Pyhton files to load and execute.
+
+    # Put here the full names of files you want executed with execfile(file).  If
+    # you want complicated initialization, just write whatever you want in a
+    # regular python file and load it from here.
+
+    # Filenames defined here (which *must* include the extension) are searched for
+    # through all of sys.path. Since IPython adds your .ipython directory to
+    # sys.path, they can also be placed in your .ipython dir and will be
+    # found. Otherwise (if you want to execute things not in .ipyton nor in
+    # sys.path) give a full path (you can use ~, it gets expanded)
+
+    # Example:
+    # execfile file1.py ~/file2.py
+    # will generate
+    # execfile('file1.py')
+    # execfile('_path_to_your_home/file2.py')
+
+    # As before, each file gets its own try/except block.
+
+    execfile
+
+    # If you are feeling adventurous, you can even add functionality to IPython
+    # through here. IPython works through a global variable called __ip which
+    # exists at the time when these files are read. If you know what you are doing
+    # (read the source) you can add functions to __ip in files loaded here. 
+
+    # The file example-magic.py contains a simple but correct example. Try it:
+
+    # execfile example-magic.py
+
+    # Look at the examples in IPython/iplib.py for more details on how these magic
+    # functions need to process their arguments.
+
+    #---------------------------------------------------------------------------
+    # Section: aliases for system shell commands
+
+    # Here you can define your own names for system commands. The syntax is
+    # similar to that of the builtin %alias function:
+
+    # alias alias_name command_string
+
+    # The resulting aliases are auto-generated magic functions (hence usable as
+    # %alias_name)
+
+    # For example:
+
+    # alias myls ls -la
+
+    # will define 'myls' as an alias for executing the system command 'ls -la'.
+    # This allows you to customize IPython's environment to have the same aliases
+    # you are accustomed to from your own shell.
+
+    # You can also define aliases with parameters using %s specifiers (one per
+    # parameter):
+
+    # alias parts echo first %s second %s
+
+    # will give you in IPython:
+    # >>> %parts A B
+    # first A second B
+
+    # Use one 'alias' statement per alias you wish to define.
+
+    # alias 
+
+    #************************* end of file <ipythonrc> ************************
+
+
+ipy_user_conf.py
+----------------
+
+There should be a simple template ipy_user_conf.py file in your
+~/.ipython directory. It is a plain python module that is imported
+during IPython startup, so you can do pretty much what you want there
+- import modules, configure extensions, change options, define magic
+commands, put variables and functions in the IPython namespace,
+etc. You use the IPython extension api object, acquired by
+IPython.ipapi.get() and documented in the "IPython extension API"
+chapter, to interact with IPython. A sample ipy_user_conf.py is listed
+below for reference::
+
+    # Most of your config files and extensions will probably start
+    # with this import
+
+    import IPython.ipapi
+    ip = IPython.ipapi.get()
+
+    # You probably want to uncomment this if you did %upgrade -nolegacy
+    # import ipy_defaults    
+
+    import os   
+
+    def main():   
+
+        #ip.dbg.debugmode = True
+        ip.dbg.debug_stack()
+
+        # uncomment if you want to get ipython -p sh behaviour
+        # without having to use command line switches  
+        import ipy_profile_sh
+        import jobctrl
+
+        # Configure your favourite editor?
+        # Good idea e.g. for %edit os.path.isfile
+
+        #import ipy_editors
+
+        # Choose one of these:
+
+        #ipy_editors.scite()
+        #ipy_editors.scite('c:/opt/scite/scite.exe')
+        #ipy_editors.komodo()
+        #ipy_editors.idle()
+        # ... or many others, try 'ipy_editors??' after import to see them
+
+        # Or roll your own:
+        #ipy_editors.install_editor("c:/opt/jed +$line $file")
+
+
+        o = ip.options
+        # An example on how to set options
+        #o.autocall = 1
+        o.system_verbose = 0
+
+        #import_all("os sys")
+        #execf('~/_ipython/ns.py')
+
+
+        # -- prompt
+        # A different, more compact set of prompts from the default ones, that
+        # always show your current location in the filesystem:
+
+        #o.prompt_in1 = r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Normal\n\C_Green|\#>'
+        #o.prompt_in2 = r'.\D: '
+        #o.prompt_out = r'[\#] '
+
+        # Try one of these color settings if you can't read the text easily
+        # autoexec is a list of IPython commands to execute on startup
+        #o.autoexec.append('%colors LightBG')
+        #o.autoexec.append('%colors NoColor')
+        o.autoexec.append('%colors Linux')
+
+
+    # some config helper functions you can use 
+    def import_all(modules):
+        """ Usage: import_all("os sys") """ 
+        for m in modules.split():
+            ip.ex("from %s import *" % m)
+
+    def execf(fname):
+        """ Execute a file in user namespace """
+        ip.ex('execfile("%s")' % os.path.expanduser(fname))
+
+    main()
+
+.. _Prompts:
+
+Fine-tuning your prompt
+-----------------------
+
+IPython's prompts can be customized using a syntax similar to that of
+the bash shell. Many of bash's escapes are supported, as well as a few
+additional ones. We list them below::
+
+    \#
+        the prompt/history count number. This escape is automatically
+        wrapped in the coloring codes for the currently active color scheme. 
+    \N
+        the 'naked' prompt/history count number: this is just the number
+        itself, without any coloring applied to it. This lets you produce
+        numbered prompts with your own colors. 
+    \D
+        the prompt/history count, with the actual digits replaced by dots.
+        Used mainly in continuation prompts (prompt_in2) 
+    \w
+        the current working directory 
+    \W
+        the basename of current working directory 
+    \Xn
+        where $n=0\ldots5.$ The current working directory, with $HOME
+        replaced by ~, and filtered out to contain only $n$ path elements 
+    \Yn
+        Similar to \Xn, but with the $n+1$ element included if it is ~ (this
+        is similar to the behavior of the %cn escapes in tcsh) 
+    \u
+        the username of the current user 
+    \$
+        if the effective UID is 0, a #, otherwise a $ 
+    \h
+        the hostname up to the first '.' 
+    \H
+        the hostname 
+    \n
+        a newline 
+    \r
+        a carriage return 
+    \v
+        IPython version string 
+
+In addition to these, ANSI color escapes can be insterted into the
+prompts, as \C_ColorName. The list of valid color names is: Black, Blue,
+Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray,
+LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White,
+Yellow.
+
+Finally, IPython supports the evaluation of arbitrary expressions in
+your prompt string. The prompt strings are evaluated through the syntax
+of PEP 215, but basically you can use $x.y to expand the value of x.y,
+and for more complicated expressions you can use braces: ${foo()+x} will
+call function foo and add to it the value of x, before putting the
+result into your prompt. For example, using
+prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' 
+will print the result of the uptime command on each prompt (assuming the
+commands module has been imported in your ipythonrc file).
+
+
+      Prompt examples
+
+The following options in an ipythonrc file will give you IPython's
+default prompts::
+
+    prompt_in1 'In [\#]:' 
+    prompt_in2 '   .\D.:' 
+    prompt_out 'Out[\#]:'
+
+which look like this::
+
+    In [1]: 1+2 
+    Out[1]: 3
+
+    In [2]: for i in (1,2,3): 
+       ...:    print i, 
+       ...: 
+    1 2 3
+
+These will give you a very colorful prompt with path information::
+
+    #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' 
+    prompt_in2 ' ..\D>' 
+    prompt_out '<\#>'
+
+which look like this::
+
+    fperez[~/ipython]1> 1+2 
+                    <1> 3 
+    fperez[~/ipython]2> for i in (1,2,3): 
+                   ...>     print i, 
+                   ...> 
+    1 2 3
+
+
+.. _Profiles:
+
+IPython profiles
+----------------
+
+As we already mentioned, IPython supports the -profile command-line
+option (see sec. `command line options`_). A profile is nothing more
+than a particular configuration file like your basic ipythonrc one,
+but with particular customizations for a specific purpose. When you
+start IPython with 'ipython -profile <name>', it assumes that in your
+IPYTHONDIR there is a file called ipythonrc-<name> or
+ipy_profile_<name>.py, and loads it instead of the normal ipythonrc.
+
+This system allows you to maintain multiple configurations which load
+modules, set options, define functions, etc. suitable for different
+tasks and activate them in a very simple manner. In order to avoid
+having to repeat all of your basic options (common things that don't
+change such as your color preferences, for example), any profile can
+include another configuration file. The most common way to use profiles
+is then to have each one include your basic ipythonrc file as a starting
+point, and then add further customizations.
+
+IPython as your default Python environment
+==========================================
+
+Python honors the environment variable PYTHONSTARTUP and will execute at
+startup the file referenced by this variable. If you put at the end of
+this file the following two lines of code::
+
+    import IPython 
+    IPython.Shell.IPShell().mainloop(sys_exit=1)
+
+then IPython will be your working environment anytime you start Python.
+The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
+it finishes, otherwise you'll be back at the normal Python '>>>'
+prompt.
+
+This is probably useful to developers who manage multiple Python
+versions and don't want to have correspondingly multiple IPython
+versions. Note that in this mode, there is no way to pass IPython any
+command-line options, as those are trapped first by Python itself.
+
+.. _Embedding:
+
+Embedding IPython
+=================
+
+It is possible to start an IPython instance inside your own Python
+programs. This allows you to evaluate dynamically the state of your
+code, operate with your variables, analyze them, etc. Note however that
+any changes you make to values while in the shell do not propagate back
+to the running code, so it is safe to modify your values because you
+won't break your code in bizarre ways by doing so.
+
+This feature allows you to easily have a fully functional python
+environment for doing object introspection anywhere in your code with a
+simple function call. In some cases a simple print statement is enough,
+but if you need to do more detailed analysis of a code fragment this
+feature can be very valuable.
+
+It can also be useful in scientific computing situations where it is
+common to need to do some automatic, computationally intensive part and
+then stop to look at data, plots, etc.
+Opening an IPython instance will give you full access to your data and
+functions, and you can resume program execution once you are done with
+the interactive part (perhaps to stop again later, as many times as
+needed).
+
+The following code snippet is the bare minimum you need to include in
+your Python programs for this to work (detailed examples follow later)::
+
+    from IPython.Shell import IPShellEmbed
+
+    ipshell = IPShellEmbed()
+
+    ipshell() # this call anywhere in your program will start IPython
+
+You can run embedded instances even in code which is itself being run at
+the IPython interactive prompt with '%run <filename>'. Since it's easy
+to get lost as to where you are (in your top-level IPython or in your
+embedded one), it's a good idea in such cases to set the in/out prompts
+to something different for the embedded instances. The code examples
+below illustrate this.
+
+You can also have multiple IPython instances in your program and open
+them separately, for example with different options for data
+presentation. If you close and open the same instance multiple times,
+its prompt counters simply continue from each execution to the next.
+
+Please look at the docstrings in the Shell.py module for more details on
+the use of this system.
+
+The following sample file illustrating how to use the embedding
+functionality is provided in the examples directory as example-embed.py.
+It should be fairly self-explanatory::
+
+
+    #!/usr/bin/env python
+
+    """An example of how to embed an IPython shell into a running program.
+
+    Please see the documentation in the IPython.Shell module for more details.
+
+    The accompanying file example-embed-short.py has quick code fragments for
+    embedding which you can cut and paste in your code once you understand how
+    things work.
+
+    The code in this file is deliberately extra-verbose, meant for learning."""
+
+    # The basics to get you going:
+
+    # IPython sets the __IPYTHON__ variable so you can know if you have nested
+    # copies running.
+
+    # Try running this code both at the command line and from inside IPython (with
+    # %run example-embed.py)
+    try:
+        __IPYTHON__
+    except NameError:
+        nested = 0
+        args = ['']
+    else:
+        print "Running nested copies of IPython."
+        print "The prompts for the nested copy have been modified"
+        nested = 1
+        # what the embedded instance will see as sys.argv:
+        args = ['-pi1','In <\\#>: ','-pi2','   .\\D.: ',
+                '-po','Out<\\#>: ','-nosep']
+
+    # First import the embeddable shell class
+    from IPython.Shell import IPShellEmbed
+
+    # Now create an instance of the embeddable shell. The first argument is a
+    # string with options exactly as you would type them if you were starting
+    # IPython at the system command line. Any parameters you want to define for
+    # configuration can thus be specified here.
+    ipshell = IPShellEmbed(args,
+                           banner = 'Dropping into IPython',
+                           exit_msg = 'Leaving Interpreter, back to program.')
+
+    # Make a second instance, you can have as many as you want.
+    if nested:
+        args[1] = 'In2<\\#>'
+    else:
+        args = ['-pi1','In2<\\#>: ','-pi2','   .\\D.: ',
+                '-po','Out<\\#>: ','-nosep']
+    ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
+
+    print '\nHello. This is printed from the main controller program.\n'
+
+    # You can then call ipshell() anywhere you need it (with an optional
+    # message):
+    ipshell('***Called from top level. '
+            'Hit Ctrl-D to exit interpreter and continue program.\n'
+            'Note that if you use %kill_embedded, you can fully deactivate\n'
+            'This embedded instance so it will never turn on again')
+
+    print '\nBack in caller program, moving along...\n'
+
+    #---------------------------------------------------------------------------
+    # More details:
+
+    # IPShellEmbed instances don't print the standard system banner and
+    # messages. The IPython banner (which actually may contain initialization
+    # messages) is available as <instance>.IP.BANNER in case you want it.
+
+    # IPShellEmbed instances print the following information everytime they
+    # start:
+
+    # - A global startup banner.
+
+    # - A call-specific header string, which you can use to indicate where in the
+    # execution flow the shell is starting.
+
+    # They also print an exit message every time they exit.
+
+    # Both the startup banner and the exit message default to None, and can be set
+    # either at the instance constructor or at any other time with the
+    # set_banner() and set_exit_msg() methods.
+
+    # The shell instance can be also put in 'dummy' mode globally or on a per-call
+    # basis. This gives you fine control for debugging without having to change
+    # code all over the place.
+
+    # The code below illustrates all this.
+
+
+    # This is how the global banner and exit_msg can be reset at any point
+    ipshell.set_banner('Entering interpreter - New Banner')
+    ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
+
+    def foo(m):
+        s = 'spam'
+        ipshell('***In foo(). Try @whos, or print s or m:')
+        print 'foo says m = ',m
+
+    def bar(n):
+        s = 'eggs'
+        ipshell('***In bar(). Try @whos, or print s or n:')
+        print 'bar says n = ',n
+
+    # Some calls to the above functions which will trigger IPython:
+    print 'Main program calling foo("eggs")\n'
+    foo('eggs')
+
+    # The shell can be put in 'dummy' mode where calls to it silently return. This
+    # allows you, for example, to globally turn off debugging for a program with a
+    # single call.
+    ipshell.set_dummy_mode(1)
+    print '\nTrying to call IPython which is now "dummy":'
+    ipshell()
+    print 'Nothing happened...'
+    # The global 'dummy' mode can still be overridden for a single call
+    print '\nOverriding dummy mode manually:'
+    ipshell(dummy=0)
+
+    # Reactivate the IPython shell
+    ipshell.set_dummy_mode(0)
+
+    print 'You can even have multiple embedded instances:'
+    ipshell2()
+
+    print '\nMain program calling bar("spam")\n'
+    bar('spam')
+
+    print 'Main program finished. Bye!'
+
+    #********************** End of file <example-embed.py> ***********************
+
+Once you understand how the system functions, you can use the following
+code fragments in your programs which are ready for cut and paste::
+
+
+    """Quick code snippets for embedding IPython into other programs.
+
+    See example-embed.py for full details, this file has the bare minimum code for
+    cut and paste use once you understand how to use the system."""
+
+    #---------------------------------------------------------------------------
+    # This code loads IPython but modifies a few things if it detects it's running
+    # embedded in another IPython session (helps avoid confusion)
+
+    try:
+        __IPYTHON__
+    except NameError:
+        argv = ['']
+        banner = exit_msg = ''
+    else:
+        # Command-line options for IPython (a list like sys.argv)
+        argv = ['-pi1','In <\\#>:','-pi2','   .\\D.:','-po','Out<\\#>:']
+        banner = '*** Nested interpreter ***'
+        exit_msg = '*** Back in main IPython ***'
+
+    # First import the embeddable shell class
+    from IPython.Shell import IPShellEmbed
+    # Now create the IPython shell instance. Put ipshell() anywhere in your code
+    # where you want it to open.
+    ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
+
+    #---------------------------------------------------------------------------
+    # This code will load an embeddable IPython shell always with no changes for
+    # nested embededings.
+
+    from IPython.Shell import IPShellEmbed
+    ipshell = IPShellEmbed()
+    # Now ipshell() will open IPython anywhere in the code.
+
+    #---------------------------------------------------------------------------
+    # This code loads an embeddable shell only if NOT running inside
+    # IPython. Inside IPython, the embeddable shell variable ipshell is just a
+    # dummy function.
+
+    try:
+        __IPYTHON__
+    except NameError:
+        from IPython.Shell import IPShellEmbed
+        ipshell = IPShellEmbed()
+        # Now ipshell() will open IPython anywhere in the code
+    else:
+        # Define a dummy ipshell() so the same code doesn't crash inside an
+        # interactive IPython
+        def ipshell(): pass
+
+    #******************* End of file <example-embed-short.py> ********************
+
+Using the Python debugger (pdb)
+===============================
+
+Running entire programs via pdb
+-------------------------------
+
+pdb, the Python debugger, is a powerful interactive debugger which
+allows you to step through code, set breakpoints, watch variables,
+etc.  IPython makes it very easy to start any script under the control
+of pdb, regardless of whether you have wrapped it into a 'main()'
+function or not. For this, simply type '%run -d myscript' at an
+IPython prompt. See the %run command's documentation (via '%run?' or
+in Sec. magic_ for more details, including how to control where pdb
+will stop execution first.
+
+For more information on the use of the pdb debugger, read the included
+pdb.doc file (part of the standard Python distribution). On a stock
+Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
+easiest way to read it is by using the help() function of the pdb module
+as follows (in an IPython prompt):
+
+In [1]: import pdb 
+In [2]: pdb.help()
+
+This will load the pdb.doc document in a file viewer for you automatically.
+
+
+Automatic invocation of pdb on exceptions
+-----------------------------------------
+
+IPython, if started with the -pdb option (or if the option is set in
+your rc file) can call the Python pdb debugger every time your code
+triggers an uncaught exception. This feature
+can also be toggled at any time with the %pdb magic command. This can be
+extremely useful in order to find the origin of subtle bugs, because pdb
+opens up at the point in your code which triggered the exception, and
+while your program is at this point 'dead', all the data is still
+available and you can walk up and down the stack frame and understand
+the origin of the problem.
+
+Furthermore, you can use these debugging facilities both with the
+embedded IPython mode and without IPython at all. For an embedded shell
+(see sec. Embedding_), simply call the constructor with
+'-pdb' in the argument string and automatically pdb will be called if an
+uncaught exception is triggered by your code.
+
+For stand-alone use of the feature in your programs which do not use
+IPython at all, put the following lines toward the top of your 'main'
+routine::
+
+    import sys,IPython.ultraTB  
+    sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
+    color_scheme='Linux', call_pdb=1)
+
+The mode keyword can be either 'Verbose' or 'Plain', giving either very
+detailed or normal tracebacks respectively. The color_scheme keyword can
+be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
+options which can be set in IPython with -colors and -xmode.
+
+This will give any of your programs detailed, colored tracebacks with
+automatic invocation of pdb.
+
+
+Extensions for syntax processing
+================================
+
+This isn't for the faint of heart, because the potential for breaking
+things is quite high. But it can be a very powerful and useful feature.
+In a nutshell, you can redefine the way IPython processes the user input
+line to accept new, special extensions to the syntax without needing to
+change any of IPython's own code.
+
+In the IPython/Extensions directory you will find some examples
+supplied, which we will briefly describe now. These can be used 'as is'
+(and both provide very useful functionality), or you can use them as a
+starting point for writing your own extensions.
+
+
+Pasting of code starting with '>>> ' or '... '
+----------------------------------------------
+
+In the python tutorial it is common to find code examples which have
+been taken from real python sessions. The problem with those is that all
+the lines begin with either '>>> ' or '... ', which makes it impossible
+to paste them all at once. One must instead do a line by line manual
+copying, carefully removing the leading extraneous characters.
+
+This extension identifies those starting characters and removes them
+from the input automatically, so that one can paste multi-line examples
+directly into IPython, saving a lot of time. Please look at the file
+InterpreterPasteInput.py in the IPython/Extensions directory for details
+on how this is done.
+
+IPython comes with a special profile enabling this feature, called
+tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
+will be available. In a normal IPython session you can activate the
+feature by importing the corresponding module with:
+In [1]: import IPython.Extensions.InterpreterPasteInput
+
+The following is a 'screenshot' of how things work when this extension
+is on, copying an example from the standard tutorial::
+
+    IPython profile: tutorial 
+
+    *** Pasting of code with ">>>" or "..." has been enabled. 
+
+    In [1]: >>> def fib2(n): # return Fibonacci series up to n 
+       ...: ...     """Return a list containing the Fibonacci series up to
+    n.""" 
+       ...: ...     result = [] 
+       ...: ...     a, b = 0, 1 
+       ...: ...     while b < n: 
+       ...: ...         result.append(b)    # see below 
+       ...: ...         a, b = b, a+b 
+       ...: ...     return result 
+       ...: 
+
+    In [2]: fib2(10) 
+    Out[2]: [1, 1, 2, 3, 5, 8]
+
+Note that as currently written, this extension does not recognize
+IPython's prompts for pasting. Those are more complicated, since the
+user can change them very easily, they involve numbers and can vary in
+length. One could however extract all the relevant information from the
+IPython instance and build an appropriate regular expression. This is
+left as an exercise for the reader.
+
+
+Input of physical quantities with units
+---------------------------------------
+
+The module PhysicalQInput allows a simplified form of input for physical
+quantities with units. This file is meant to be used in conjunction with
+the PhysicalQInteractive module (in the same directory) and
+Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
+(http://dirac.cnrs-orleans.fr/ScientificPython/).
+
+The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
+but these must be declared as instances of a class. For example, to
+define v as a velocity of 3 m/s, normally you would write::
+
+    In [1]: v = PhysicalQuantity(3,'m/s')
+
+Using the PhysicalQ_Input extension this can be input instead as: 
+In [1]: v = 3 m/s
+which is much more convenient for interactive use (even though it is
+blatantly invalid Python syntax).
+
+The physics profile supplied with IPython (enabled via 'ipython -p
+physics') uses these extensions, which you can also activate with:
+
+from math import * # math MUST be imported BEFORE PhysicalQInteractive 
+from IPython.Extensions.PhysicalQInteractive import * 
+import IPython.Extensions.PhysicalQInput
+
+
+IPython as a system shell - the 'Sh' profile
+============================================
+
+The 'sh' profile optimizes IPython for system shell usage. Apart from
+certain job control functionality that is present in unix (ctrl+z does
+"suspend"), the sh profile should provide you with most of the
+functionality you use daily in system shell, and more. Invoke IPython
+in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching
+the "pysh" shortcut in start menu.
+
+If you want to use the features of sh profile as your defaults (which
+might be a good idea if you use other profiles a lot of the time but
+still want the convenience of sh profile), add ``import ipy_profile_sh``
+to your ~/.ipython/ipy_user_conf.py.
+
+The 'sh' profile is different from the default profile in that:
+
+ * Prompt shows the current directory
+ * Spacing between prompts and input is more compact (no padding with
+   empty lines). The startup banner is more compact as well.
+ * System commands are directly available (in alias table) without
+   requesting %rehashx - however, if you install new programs along
+   your PATH, you might want to run %rehashx to update the persistent
+   alias table
+ * Macros are stored in raw format by default. That is, instead of
+   '_ip.system("cat foo"), the macro will contain text 'cat foo')
+ * Autocall is in full mode
+ * Calling "up" does "cd .."
+
+The 'sh' profile is different from the now-obsolete (and unavailable)
+'pysh' profile in that:
+
+ * '$$var = command' and '$var = command' syntax is not supported
+ * anymore. Use 'var = !command' instead (incidentally, this is
+ * available in all IPython profiles). Note that !!command *will*
+ * work.
+
+Aliases
+-------
+
+All of your $PATH has been loaded as IPython aliases, so you should be
+able to type any normal system command and have it executed. See
+%alias?  and %unalias? for details on the alias facilities. See also
+%rehashx? for details on the mechanism used to load $PATH.
+
+
+Directory management
+--------------------
+
+Since each command passed by ipython to the underlying system is executed
+in a subshell which exits immediately, you can NOT use !cd to navigate
+the filesystem.
+
+IPython provides its own builtin '%cd' magic command to move in the
+filesystem (the % is not required with automagic on). It also maintains
+a list of visited directories (use %dhist to see it) and allows direct
+switching to any of them. Type 'cd?' for more details.
+
+%pushd, %popd and %dirs are provided for directory stack handling.
+
+
+Enabled extensions
+------------------
+
+Some extensions, listed below, are enabled as default in this profile.
+
+envpersist
+++++++++++
+
+%env can be used to "remember" environment variable manipulations. Examples::
+
+	%env - Show all environment variables
+	%env VISUAL=jed  - set VISUAL to jed
+	%env PATH+=;/foo - append ;foo to PATH
+	%env PATH+=;/bar - also append ;bar to PATH
+	%env PATH-=/wbin; - prepend /wbin; to PATH
+	%env -d VISUAL   - forget VISUAL persistent val
+	%env -p          - print all persistent env modifications
+
+ipy_which
++++++++++
+
+%which magic command. Like 'which' in unix, but knows about ipython aliases.
+
+Example::
+
+ [C:/ipython]|14> %which st
+ st -> start .
+ [C:/ipython]|15> %which d
+ d -> dir /w /og /on
+ [C:/ipython]|16> %which cp
+ cp -> cp
+   == c:\bin\cp.exe
+ c:\bin\cp.exe
+
+ipy_app_completers
+++++++++++++++++++
+
+Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu.
+
+ipy_rehashdir
++++++++++++++
+
+Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir::
+
+ [~]|22> cd c:/opt/PuTTY/
+ [c:opt/PuTTY]|23> rehashdir .
+              <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000']
+
+Now, you can execute any of those commams directly::
+
+ [c:opt/PuTTY]|24> cd
+ [~]|25> putty
+
+(the putty window opens).
+
+If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop::
+
+ [~]|27> for a in _23:
+    |..>     %store $a
+    |..>
+    |..>
+ Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe')
+ Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe')
+ Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe')
+ Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe')
+ ...
+
+mglob
++++++
+
+Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples::
+
+ [c:/ipython]|9> mglob *.py
+ [c:/ipython]|10> mglob *.py rec:*.txt
+ [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:.
+
+Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'.
+
+
+Prompt customization
+--------------------
+
+The sh profile uses the following prompt configurations::
+
+    o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>'
+    o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>'
+
+You can change the prompt configuration to your liking by editing
+ipy_user_conf.py.  
+
+String lists
+============
+
+String lists (IPython.genutils.SList) are handy way to process output
+from system commands. They are produced by ``var = !cmd`` syntax.
+
+First, we acquire the output of 'ls -l'::
+
+    [Q:doc/examples]|2> lines = !ls -l
+     ==
+    ['total 23',
+     '-rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py',
+     '-rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py',
+     '-rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py',
+     '-rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py',
+     '-rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py',
+     '-rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py',
+     '-rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc']
+
+Now, let's take a look at the contents of 'lines' (the first number is
+the list element number)::
+
+    [Q:doc/examples]|3> lines
+                    <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
+
+    0: total 23
+    1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
+    2: -rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py
+    3: -rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py
+    4: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
+    5: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
+    6: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
+    7: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
+
+Now, let's filter out the 'embed' lines::
+
+    [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1)
+    [Q:doc/examples]|5> l2
+                    <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
+
+    0: total 23
+    1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
+    2: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
+    3: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
+    4: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
+    5: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
+
+Now, we want strings having just file names and permissions::
+
+    [Q:doc/examples]|6> l2.fields(8,0)
+                    <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
+
+    0: total
+    1: example-demo.py -rw-rw-rw-
+    2: example-gnuplot.py -rwxrwxrwx
+    3: extension.py -rwxrwxrwx
+    4: seteditor.py -rwxrwxrwx
+    5: seteditor.pyc -rwxrwxrwx
+
+Note how the line with 'total' does not raise IndexError.
+
+If you want to split these (yielding lists), call fields() without
+arguments::
+
+    [Q:doc/examples]|7> _.fields()
+                    <7>
+    [['total'],
+     ['example-demo.py', '-rw-rw-rw-'],
+     ['example-gnuplot.py', '-rwxrwxrwx'],
+     ['extension.py', '-rwxrwxrwx'],
+     ['seteditor.py', '-rwxrwxrwx'],
+     ['seteditor.pyc', '-rwxrwxrwx']]
+
+If you want to pass these separated with spaces to a command (typical
+for lists if files), use the .s property::
+
+
+    [Q:doc/examples]|13> files = l2.fields(8).s
+    [Q:doc/examples]|14> files
+                    <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc'
+    [Q:doc/examples]|15> ls $files
+    example-demo.py  example-gnuplot.py  extension.py  seteditor.py  seteditor.pyc
+
+SLists are inherited from normal python lists, so every list method is
+available::
+
+    [Q:doc/examples]|21> lines.append('hey')
+
+
+Real world example: remove all files outside version control
+------------------------------------------------------------
+
+First, capture output of "hg status"::
+
+    [Q:/ipython]|28> out = !hg status
+     ==
+    ['M IPython\\Extensions\\ipy_kitcfg.py',
+     'M IPython\\Extensions\\ipy_rehashdir.py',
+    ...
+     '? build\\lib\\IPython\\Debugger.py',
+     '? build\\lib\\IPython\\Extensions\\InterpreterExec.py',
+     '? build\\lib\\IPython\\Extensions\\InterpreterPasteInput.py',
+    ...
+
+(lines starting with ? are not under version control).
+
+::
+
+    [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1)
+    [Q:/ipython]|36> junk
+                <36> SList (.p, .n, .l, .s, .grep(), .fields() availab
+    ...
+    10: build\bdist.win32\winexe\temp\_ctypes.py
+    11: build\bdist.win32\winexe\temp\_hashlib.py
+    12: build\bdist.win32\winexe\temp\_socket.py
+
+Now we can just remove these files by doing 'rm $junk.s'. 
+
+The .s, .n, .p properties
+-------------------------
+
+The '.s' property returns one string where lines are separated by
+single space (for convenient passing to system commands). The '.n'
+property return one string where the lines are separated by '\n'
+(i.e. the original output of the function). If the items in string
+list are file names, '.p' can be used to get a list of "path" objects
+for convenient file manipulation.
+
+
+Threading support
+=================
+
+WARNING: The threading support is still somewhat experimental, and it
+has only seen reasonable testing under Linux. Threaded code is
+particularly tricky to debug, and it tends to show extremely
+platform-dependent behavior. Since I only have access to Linux machines,
+I will have to rely on user's experiences and assistance for this area
+of IPython to improve under other platforms.
+
+IPython, via the -gthread , -qthread, -q4thread and -wthread options
+(described in Sec. `Threading options`_), can run in
+multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications
+respectively. These GUI toolkits need to control the python main loop of
+execution, so under a normal Python interpreter, starting a pyGTK, Qt3,
+Qt4 or WXPython application will immediately freeze the shell.
+
+IPython, with one of these options (you can only use one at a time),
+separates the graphical loop and IPython's code execution run into
+different threads. This allows you to test interactively (with %run, for
+example) your GUI code without blocking.
+
+A nice mini-tutorial on using IPython along with the Qt Designer
+application is available at the SciPy wiki:
+http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
+
+
+Tk issues
+---------
+
+As indicated in Sec. `Threading options`_, a special -tk option is
+provided to try and allow Tk graphical applications to coexist
+interactively with WX, Qt or GTK ones. Whether this works at all,
+however, is very platform and configuration dependent. Please
+experiment with simple test cases before committing to using this
+combination of Tk and GTK/Qt/WX threading in a production environment.
+
+
+I/O pitfalls
+------------
+
+Be mindful that the Python interpreter switches between threads every
+$N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
+value can be read by using the sys.getcheckinterval() function, and it
+can be reset via sys.setcheckinterval(N). This switching of threads can
+cause subtly confusing effects if one of your threads is doing file I/O.
+In text mode, most systems only flush file buffers when they encounter a
+'\n'. An instruction as simple as:: 
+
+  print >> filehandle, ''hello world''
+
+actually consists of several bytecodes, so it is possible that the
+newline does not reach your file before the next thread switch.
+Similarly, if you are writing to a file in binary mode, the file won't
+be flushed until the buffer fills, and your other thread may see
+apparently truncated files.
+
+For this reason, if you are using IPython's thread support and have (for
+example) a GUI application which will read data generated by files
+written to from the IPython thread, the safest approach is to open all
+of your files in unbuffered mode (the third argument to the file/open
+function is the buffering value)::
+
+  filehandle = open(filename,mode,0)
+
+This is obviously a brute force way of avoiding race conditions with the
+file buffering. If you want to do it cleanly, and you have a resource
+which is being shared by the interactive IPython loop and your GUI
+thread, you should really handle it with thread locking and
+syncrhonization properties. The Python documentation discusses these.
+
+.. _Interactive demos:
+
+Interactive demos with IPython
+==============================
+
+IPython ships with a basic system for running scripts interactively in
+sections, useful when presenting code to audiences. A few tags embedded
+in comments (so that the script remains valid Python code) divide a file
+into separate blocks, and the demo can be run one block at a time, with
+IPython printing (with syntax highlighting) the block before executing
+it, and returning to the interactive prompt after each block. The
+interactive namespace is updated after each block is run with the
+contents of the demo's namespace.
+
+This allows you to show a piece of code, run it and then execute
+interactively commands based on the variables just created. Once you
+want to continue, you simply execute the next block of the demo. The
+following listing shows the markup necessary for dividing a script into
+sections for execution as a demo::
+
+
+    """A simple interactive demo to illustrate the use of IPython's Demo class.
+
+    Any python script can be run as a demo, but that does little more than showing
+    it on-screen, syntax-highlighted in one shot.  If you add a little simple
+    markup, you can stop at specified intervals and return to the ipython prompt,
+    resuming execution later.
+    """
+
+    print 'Hello, welcome to an interactive IPython demo.'
+    print 'Executing this block should require confirmation before proceeding,'
+    print 'unless auto_all has been set to true in the demo object'
+
+    # The mark below defines a block boundary, which is a point where IPython will
+    # stop execution and return to the interactive prompt.
+    # Note that in actual interactive execution, 
+    # <demo> --- stop ---
+
+    x = 1
+    y = 2
+
+    # <demo> --- stop ---
+
+    # the mark below makes this block as silent
+    # <demo> silent
+
+    print 'This is a silent block, which gets executed but not printed.'
+
+    # <demo> --- stop ---
+    # <demo> auto
+    print 'This is an automatic block.'
+    print 'It is executed without asking for confirmation, but printed.'
+    z = x+y
+
+    print 'z=',x
+
+    # <demo> --- stop ---
+    # This is just another normal block.
+    print 'z is now:', z
+
+    print 'bye!'
+
+In order to run a file as a demo, you must first make a Demo object out
+of it. If the file is named myscript.py, the following code will make a
+demo::
+
+    from IPython.demo import Demo
+
+    mydemo = Demo('myscript.py')
+
+This creates the mydemo object, whose blocks you run one at a time by
+simply calling the object with no arguments. If you have autocall active
+in IPython (the default), all you need to do is type::
+
+    mydemo 
+
+and IPython will call it, executing each block. Demo objects can be
+restarted, you can move forward or back skipping blocks, re-execute the
+last block, etc. Simply use the Tab key on a demo object to see its
+methods, and call '?' on them to see their docstrings for more usage
+details. In addition, the demo module itself contains a comprehensive
+docstring, which you can access via::
+
+    from IPython import demo
+
+    demo?
+
+Limitations: It is important to note that these demos are limited to
+fairly simple uses. In particular, you can not put division marks in
+indented code (loops, if statements, function definitions, etc.)
+Supporting something like this would basically require tracking the
+internal execution state of the Python interpreter, so only top-level
+divisions are allowed. If you want to be able to open an IPython
+instance at an arbitrary point in a program, you can use IPython's
+embedding facilities, described in detail in Sec. 9
+
+
+.. _Matplotlib support:
+
+Plotting with matplotlib
+========================
+
+The matplotlib library (http://matplotlib.sourceforge.net
+http://matplotlib.sourceforge.net) provides high quality 2D plotting for
+Python. Matplotlib can produce plots on screen using a variety of GUI
+toolkits, including Tk, GTK and WXPython. It also provides a number of
+commands useful for scientific computing, all with a syntax compatible
+with that of the popular Matlab program.
+
+IPython accepts the special option -pylab (Sec. `Command line
+options`_). This configures it to support matplotlib, honoring the
+settings in the .matplotlibrc file. IPython will detect the user's
+choice of matplotlib GUI backend, and automatically select the proper
+threading model to prevent blocking. It also sets matplotlib in
+interactive mode and modifies %run slightly, so that any
+matplotlib-based script can be executed using %run and the final
+show() command does not block the interactive shell.
+
+The -pylab option must be given first in order for IPython to
+configure its threading mode. However, you can still issue other
+options afterwards. This allows you to have a matplotlib-based
+environment customized with additional modules using the standard
+IPython profile mechanism (Sec. Profiles_): ''ipython -pylab -p
+myprofile'' will load the profile defined in ipythonrc-myprofile after
+configuring matplotlib.
+
+IPython Extension Api
+=====================
+
+IPython api (defined in IPython/ipapi.py) is the public api that
+should be used for
+
+ * Configuration of user preferences (.ipython/ipy_user_conf.py)
+ * Creating new profiles (.ipython/ipy_profile_PROFILENAME.py)
+ * Writing extensions 
+
+Note that by using the extension api for configuration (editing
+ipy_user_conf.py instead of ipythonrc), you get better validity checks
+and get richer functionality - for example, you can import an
+extension and call functions in it to configure it for your purposes.
+
+For an example extension (the 'sh' profile), see
+IPython/Extensions/ipy_profile_sh.py.
+
+For the last word on what's available, see the source code of
+IPython/ipapi.py.
+
+
+Getting started
+---------------
+
+If you want to define an extension, create a normal python module that
+can be imported. The module will access IPython functionality through
+the 'ip' object defined below.
+
+If you are creating a new profile (e.g. foobar), name the module as
+'ipy_profile_foobar.py' and put it in your ~/.ipython directory. Then,
+when you start ipython with the '-p foobar' argument, the module is
+automatically imported on ipython startup.
+
+If you are just doing some per-user configuration, you can either 
+
+ * Put the commands directly into ipy_user_conf.py. 
+
+ * Create a new module with your customization code and import *that*
+   module in ipy_user_conf.py. This is preferable to the first approach,
+   because now you can reuse and distribute your customization code.
+
+Getting a handle to the api
+---------------------------
+
+Put this in the start of your module::
+
+    #!python
+    import IPython.ipapi
+    ip = IPython.ipapi.get()
+
+The 'ip' object will then be used for accessing IPython
+functionality. 'ip' will mean this api object in all the following
+code snippets. The same 'ip' that we just acquired is always
+accessible in interactive IPython sessions by the name _ip - play with
+it like this::
+
+    [~\_ipython]|81> a = 10
+    [~\_ipython]|82> _ip.e
+    _ip.ev           _ip.ex           _ip.expose_magic
+    [~\_ipython]|82> _ip.ev('a+13')
+                <82> 23
+
+The _ip object is also used in some examples in this document - it can
+be substituted by 'ip' in non-interactive use.
+
+Changing options
+----------------
+
+The ip object has 'options' attribute that can be used te get/set
+configuration options (just as in the ipythonrc file)::
+
+    o = ip.options
+    o.autocall = 2
+    o.automagic = 1
+
+Executing statements in IPython namespace with 'ex' and 'ev'
+------------------------------------------------------------
+
+Often, you want to e.g. import some module or define something that
+should be visible in IPython namespace. Use ``ip.ev`` to
+*evaluate* (calculate the value of) expression and ``ip.ex`` to
+'''execute''' a statement::
+
+    # path module will be visible to the interactive session
+    ip.ex("from path import path" )
+
+    # define a handy function 'up' that changes the working directory
+
+    ip.ex('import os')
+    ip.ex("def up(): os.chdir('..')")
+
+
+    # _i2 has the input history entry #2, print its value in uppercase.
+    print ip.ev('_i2.upper()')
+
+Accessing the IPython namespace
+-------------------------------
+
+ip.user_ns attribute has a dictionary containing the IPython global
+namespace (the namespace visible in the interactive session).
+
+::
+
+    [~\_ipython]|84> tauno = 555
+    [~\_ipython]|85> _ip.user_ns['tauno']
+                <85> 555
+
+Defining new magic commands
+---------------------------
+
+The following example defines a new magic command, %impall. What the
+command does should be obvious::
+
+    def doimp(self, arg):
+        ip = self.api
+        ip.ex("import %s; reload(%s); from %s import *" % (
+        arg,arg,arg)
+        )
+
+    ip.expose_magic('impall', doimp)
+
+Things to observe in this example:
+
+ * Define a function that implements the magic command using the 
+   ipapi methods defined in this document
+ * The first argument of the function is 'self', i.e. the 
+   interpreter object. It shouldn't be used directly. however. 
+   The interpreter object is probably *not* going to remain stable 
+   through IPython versions.
+ * Access the ipapi through 'self.api' instead of the global 'ip' object.
+ * All the text following the magic command on the command line is 
+   contained in the second argument
+ * Expose the magic by ip.expose_magic()
+
+
+Calling magic functions and system commands
+-------------------------------------------
+
+Use ip.magic() to execute a magic function, and ip.system() to execute
+a system command::
+
+    # go to a bookmark
+    ip.magic('%cd -b relfiles')
+
+    # execute 'ls -F' system command. Interchangeable with os.system('ls'), really.
+    ip.system('ls -F')
+
+Launching IPython instance from normal python code
+--------------------------------------------------
+
+Use ipapi.launch_new_instance() with an argument that specifies the
+namespace to use. This can be useful for trivially embedding IPython
+into your program. Here's an example of normal python program test.py
+('''without''' an existing IPython session) that launches an IPython
+interpreter and regains control when the interpreter is exited::
+
+    [ipython]|1> cat test.py
+    my_ns = dict(
+        kissa = 15,
+        koira = 16)
+    import IPython.ipapi
+    print "launching IPython instance"
+    IPython.ipapi.launch_new_instance(my_ns)
+    print "Exited IPython instance!"
+    print "New vals:",my_ns['kissa'], my_ns['koira']
+
+And here's what it looks like when run (note how we don't start it
+from an ipython session)::
+
+    Q:\ipython>python test.py
+    launching IPython instance
+    Py 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] IPy 0.7.3b3.r1975
+    [ipython]|1> kissa = 444
+    [ipython]|2> koira = 555
+    [ipython]|3> Exit
+    Exited IPython instance!
+    New vals: 444 555
+
+Accessing unexposed functionality
+---------------------------------
+
+There are still many features that are not exposed via the ipapi. If
+you can't avoid using them, you can use the functionality in
+InteractiveShell object (central IPython session class, defined in
+iplib.py) through ip.IP.
+
+For example::
+
+    [~]|7> _ip.IP.expand_aliases('np','myfile.py')
+       <7> 'c:/opt/Notepad++/notepad++.exe myfile.py'
+    [~]|8>
+
+Still, it's preferable that if you encounter such a feature, contact
+the IPython team and request that the functionality be exposed in a
+future version of IPython. Things not in ipapi are more likely to
+change over time.
+
+Provided extensions
+===================
+
+You can see the list of available extensions (and profiles) by doing
+``import ipy_<TAB>``. Some extensions don't have the ``ipy_`` prefix in
+module name, so you may need to see the contents of IPython/Extensions
+folder to see what's available.
+
+You can see a brief documentation of an extension by looking at the
+module docstring::
+
+    [c:p/ipython_main]|190> import ipy_fsops
+    [c:p/ipython_main]|191> ipy_fsops?
+
+    ...
+
+    Docstring:
+        File system operations
+
+    Contains: Simple variants of normal unix shell commands (icp, imv, irm,
+    imkdir, igrep).
+
+You can also install your own extensions - the recommended way is to
+just copy the module to ~/.ipython. Extensions are typically enabled
+by just importing them (e.g. in ipy_user_conf.py), but some extensions
+require additional steps, for example::
+
+    [c:p]|192> import ipy_traits_completer
+    [c:p]|193> ipy_traits_completer.activate()    
+
+Note that extensions, even if provided in the stock IPython
+installation, are not guaranteed to have the same requirements as the
+rest of IPython - an extension may require external libraries or a
+newer version of Python than what IPython officially requires. An
+extension may also be under a more restrictive license than IPython
+(e.g. ipy_bzr is under GPL).
+
+Just for reference, the list of bundled extensions at the time of
+writing is below:
+
+astyle.py clearcmd.py envpersist.py ext_rescapture.py ibrowse.py
+igrid.py InterpreterExec.py InterpreterPasteInput.py ipipe.py
+ipy_app_completers.py ipy_autoreload.py ipy_bzr.py ipy_completers.py
+ipy_constants.py ipy_defaults.py ipy_editors.py ipy_exportdb.py
+ipy_extutil.py ipy_fsops.py ipy_gnuglobal.py ipy_kitcfg.py
+ipy_legacy.py ipy_leo.py ipy_p4.py ipy_profile_doctest.py
+ipy_profile_none.py ipy_profile_scipy.py ipy_profile_sh.py
+ipy_profile_zope.py ipy_pydb.py ipy_rehashdir.py ipy_render.py
+ipy_server.py ipy_signals.py ipy_stock_completers.py
+ipy_system_conf.py ipy_traits_completer.py ipy_vimserver.py
+ipy_which.py ipy_workdir.py jobctrl.py ledit.py numeric_formats.py
+PhysicalQInput.py PhysicalQInteractive.py pickleshare.py
+pspersistence.py win32clip.py __init__.py
+
+Reporting bugs
+==============
+
+Automatic crash reports
+-----------------------
+
+Ideally, IPython itself shouldn't crash. It will catch exceptions
+produced by you, but bugs in its internals will still crash it.
+
+In such a situation, IPython will leave a file named
+IPython_crash_report.txt in your IPYTHONDIR directory (that way if
+crashes happen several times it won't litter many directories, the
+post-mortem file is always located in the same place and new
+occurrences just overwrite the previous one). If you can mail this
+file to the developers (see sec. credits_ for names and addresses), it
+will help us a lot in understanding the cause of the problem and
+fixing it sooner.
+
+
+The bug tracker
+---------------
+
+IPython also has an online bug-tracker, located at
+http://projects.scipy.org/ipython/ipython/report/1. In addition to
+mailing the developers, it would be a good idea to file a bug report
+here. This will ensure that the issue is properly followed to
+conclusion. To report new bugs you will have to register first.
+
+You can also use this bug tracker to file feature requests.
+
+Brief history
+=============
+
+
+Origins
+-------
+
+The current IPython system grew out of the following three projects:
+
+    * [ipython] by Fernando Pérez. I was working on adding
+      Mathematica-type prompts and a flexible configuration system
+      (something better than $PYTHONSTARTUP) to the standard Python
+      interactive interpreter.
+    * [IPP] by Janko Hauser. Very well organized, great usability. Had
+      an old help system. IPP was used as the 'container' code into
+      which I added the functionality from ipython and LazyPython.
+    * [LazyPython] by Nathan Gray. Simple but very powerful. The quick
+      syntax (auto parens, auto quotes) and verbose/colored tracebacks
+      were all taken from here.
+
+When I found out about IPP and LazyPython I tried to join all three
+into a unified system. I thought this could provide a very nice
+working environment, both for regular programming and scientific
+computing: shell-like features, IDL/Matlab numerics, Mathematica-type
+prompt history and great object introspection and help facilities. I
+think it worked reasonably well, though it was a lot more work than I
+had initially planned.
+
+
+Current status
+--------------
+
+The above listed features work, and quite well for the most part. But
+until a major internal restructuring is done (see below), only bug
+fixing will be done, no other features will be added (unless very minor
+and well localized in the cleaner parts of the code).
+
+IPython consists of some 18000 lines of pure python code, of which
+roughly two thirds is reasonably clean. The rest is, messy code which
+needs a massive restructuring before any further major work is done.
+Even the messy code is fairly well documented though, and most of the
+problems in the (non-existent) class design are well pointed to by a
+PyChecker run. So the rewriting work isn't that bad, it will just be
+time-consuming.
+
+
+Future
+------
+
+See the separate new_design document for details. Ultimately, I would
+like to see IPython become part of the standard Python distribution as a
+'big brother with batteries' to the standard Python interactive
+interpreter. But that will never happen with the current state of the
+code, so all contributions are welcome.
+
+License
+=======
+
+IPython is released under the terms of the BSD license, whose general
+form can be found at:
+http://www.opensource.org/licenses/bsd-license.php. The full text of the
+IPython license is reproduced below::
+
+    IPython is released under a BSD-type license.
+
+    Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez
+    <[e-mail]>.
+
+    Copyright (c) 2001 Janko Hauser <[e-mail]> and  
+    Nathaniel Gray <[e-mail]>.
+
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    a. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+    b. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+    c. Neither the name of the copyright holders nor the names of any
+    contributors to this software may be used to endorse or promote
+    products derived from this software without specific prior written
+    permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE. 
+
+Individual authors are the holders of the copyright for their code and
+are listed in each file.
+
+Some files (DPyGetOpt.py, for example) may be licensed under different
+conditions. Ultimately each file indicates clearly the conditions under
+which its author/authors have decided to publish the code.
+
+Versions of IPython up to and including 0.6.3 were released under the
+GNU Lesser General Public License (LGPL), available at
+http://www.gnu.org/copyleft/lesser.html.
+
+Credits
+=======
+
+IPython is mainly developed by Fernando Pérez
+<[e-mail]>, but the project was born from mixing in
+Fernando's code with the IPP project by Janko Hauser
+<jhauser-AT-zscout.de> and LazyPython by Nathan Gray
+<n8gray-AT-caltech.edu>. For all IPython-related requests, please
+contact Fernando.
+
+As of early 2006, the following developers have joined the core team:
+
+    * [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
+      Google Summer of Code project to develop python interactive
+      notebooks (XML documents) and graphical interface. This project
+      was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
+      Toni Alatalo <antont-AT-an.org>
+    * [Brian Granger] <bgranger-AT-scu.edu>: extending IPython to allow
+      support for interactive parallel computing.
+    * [Ville Vainio] <vivainio-AT-gmail.com>: Ville is the new
+      maintainer for the main trunk of IPython after version 0.7.1.
+
+User or development help should be requested via the IPython mailing lists:
+
+*User list:*
+    http://scipy.net/mailman/listinfo/ipython-user 
+*Developer's list:*
+    http://scipy.net/mailman/listinfo/ipython-dev 
+
+The IPython project is also very grateful to:
+
+Bill Bumgarner <bbum-AT-friday.com>: for providing the DPyGetOpt module
+which gives very powerful and convenient handling of command-line
+options (light years ahead of what Python 2.1.1's getopt module does).
+
+Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for
+convenient and powerful string interpolation with a much nicer syntax
+than formatting through the '%' operator.
+
+Arnd Baecker <baecker-AT-physik.tu-dresden.de>: for his many very useful
+suggestions and comments, and lots of help with testing and
+documentation checking. Many of IPython's newer features are a result of
+discussions with him (bugs are still my fault, not his).
+
+Obviously Guido van Rossum and the whole Python development team, that
+goes without saying.
+
+IPython's website is generously hosted at http://ipython.scipy.orgby
+Enthought (http://www.enthought.com). I am very grateful to them and all
+of the SciPy team for their contribution.
+
+Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>,
+an O'Reilly Python editor. His Oct/11/2001 article about IPP and
+LazyPython, was what got this project started. You can read it at:
+http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html.
+
+And last but not least, all the kind IPython users who have emailed new
+code, bug reports, fixes, comments and ideas. A brief list follows,
+please let me know if I have ommitted your name by accident:
+
+    * [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
+      color problem. This bug alone caused many lost hours and
+      frustration, many thanks to him for the fix. I've always been a
+      fan of Ogg & friends, now I have one more reason to like these folks.
+      Jack is also contributing with Debian packaging and many other
+      things.
+    * [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug
+      reports, bug fixes, ideas, lots more. The ipython.el mode for
+      (X)Emacs is Alex's code, providing full support for IPython under
+      (X)Emacs.
+    * [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
+      information, Fink package management.
+    * [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
+      around the exception handling idiosyncracies of WxPython. Readline
+      and color support for Windows.
+    * [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
+      improved readline support, including fixes for Python 2.3.
+    * [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
+    * [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
+    * [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
+    * [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
+    * [Philip Hisley] <compsys-AT-starpower.net>
+    * [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
+      more.
+    * [Robin Siebler] <robinsiebler-AT-starband.net>
+    * [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
+    * [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
+    * [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
+    * [Syver Enstad] <syver-en-AT-online.no> Windows setup.
+    * [Richard] <rxe-AT-renre-europe.com> Global embedding.
+    * [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
+      compatibility.
+    * [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
+      installation.
+    * [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
+    * [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
+      documentation fixes.
+    * [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
+      ideas. Patches for Windows installer.
+    * [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
+    * [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
+    * [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
+      Win32/CygWin.
+    * [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
+      nice, lightweight string interpolation.
+    * [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
+    * [Gever Tulley] <gever-AT-helium.com> Code contributions.
+    * [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
+    * [Oliver Sander] <osander-AT-gmx.de> Bug reports.
+    * [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
+      logging module.
+    * [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
+      Fixes, enhancement suggestions for system shell use.
+    * [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
+      reports on Windows installation issues. Contributed a true Windows
+      binary installer.
+    * [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
+      to traceback printing.
+    * [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
+      prompt specials.
+    * [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
+      the multithreaded IPython.
+    * [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
+      author, helped with all the development of support for matplotlib
+      in IPyhton, including making necessary changes to matplotlib itself.
+    * [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
+    * [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
+      with (X)Emacs support, threading patches, ideas...
+    * [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
+      packaging and distribution.
+    * [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
+      tab-completing named arguments of user-defined functions.
+    * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
+      support implementation for searching namespaces.
+    * [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
+      so that when pdb is activated from within IPython, coloring, tab
+      completion and other features continue to work seamlessly.
+    * [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
+      editor invocation on syntax errors (see
+      http://www.scipy.net/roundup/ipython/issue36).
+    * [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
+      paging system.
+    * [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
+

test/test_cpaste.ipy

@@ -0,0 +1,62 b''
+"""Test cpaste magic"""
+
+tests = {'pass': ["> > > run()",
+                  ">>> > run()",
+                  "+++ run()",
+                  "++ run()",
+		  "  >>> run()"],
+
+         'fail': ["+ + run()",
+                  " ++ run()"]}
+
+from StringIO import StringIO
+import sys
+
+stdin_save = sys.stdin
+
+# NOTE: no blank lines allowed in function definition
+def testcase(code,should_fail=False):
+    """Execute code via 'cpaste' and ensure it was executed, unless
+    should_fail is set.
+
+    """
+    _ip.user_ns['code_ran'] = False
+    #
+    src = StringIO()
+    src.write('\n')
+    src.write(code)
+    src.write('\n--\n')
+    src.seek(0)
+    #
+    sys.stdin = src
+    
+    try:
+        cpaste
+    except:
+        if not should_fail:
+            raise AssertionError("Failure not expected : '%s'" %
+                                 code)
+    else:
+        assert code_ran
+        if should_fail:
+            raise AssertionError("Failure expected : '%s'" % code)
+    #
+    finally:
+        sys.stdin = stdin_save
+    #
+
+def run():
+    """Marker function: sets a flag when executed.
+
+    """
+    _ip.user_ns['code_ran'] = True
+    return 'run' # return string so '+ run()' doesn't result in success
+
+
+### Actual testing happens here
+
+for code in tests['pass']:
+    testcase(code)
+
+for code in tests['fail']:
+    testcase(code,should_fail=True)

IPython/Extensions/igrid_help.html

@@ -1,86 +1,86 b''
-<?xml version='1.0' encoding='iso-8859-1'?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
-<link rel="stylesheet" href="igrid_help.css" type="text/css" />
-<title>igrid help</title>
-</head>
-<body>
-<h1>igrid help</h1>
-
-
-<h2>Commands</h2>
-
-
-<h3>pick (P)</h3>
-<p>Pick the whole row (object is available as "_")</p>
-
-<h3>pickattr (Shift-P)</h3>
-<p>Pick the attribute under the cursor</p>
-
-<h3>pickallattrs (Shift-C)</h3>
-<p>Pick' the complete column under the cursor (i.e. the attribute under the
-cursor) from all currently fetched objects. These attributes will be returned
-as a list.</p>
-
-<h3>enter (E)</h3>
-<p>Enter the object under the cursor. (what this mean depends on the object
-itself, i.e. how it implements iteration). This opens a new browser 'level'.</p>
-
-<h3>enterattr (Shift-E)</h3>
-<p>Enter the attribute under the cursor.</p>
-
-<h3>detail (D)</h3>
-<p>Show a detail view of the object under the cursor. This shows the name,
-type, doc string and value of the object attributes (and it might show more
-attributes than in the list view, depending on the object).</p>
-
-<h3>detailattr (Shift-D)</h3>
-<p>Show a detail view of the attribute under the cursor.</p>
-
-<h3>pickrows (M)</h3>
-<p>Pick multiple selected rows (M)</p>
-
-<h3>pickrowsattr (CTRL-M)</h3>
-<p>From multiple selected rows pick the cells matching the attribute the cursor is in (CTRL-M)</p>
-
-<h3>find (CTRL-F)</h3>
-<p>Find text</p>
-
-<h3>find_next (F3)</h3>
-<p>Find next occurrence of the searchtext</p>
-
-<h3>find_previous (Shift-F3)</h3>
-<p>Find previous occurrence of the searchtext </p>
-
-<h3>sortattrasc (V)</h3>
-<p>Sort the objects (in ascending order) using the attribute under the cursor as the sort key.</p>
-
-<h3>sortattrdesc (Shift-V)</h3>
-<p>Sort the objects (in descending order) using the attribute under the cursor as the sort key.</p>
-
-<h3>leave (Backspace, DEL, X)</h3>
-<p>Close current tab (and all the tabs to the right of the current one).</h3>
-
-<h3>quit (ESC,Q)</h3>
-<p>Quit igrid and return to the IPython prompt.</p>
-
-
-<h2>Navigation</h2>
-
-
-<h3>Jump to the last column of the current row (END, CTRL-E, CTRL-Right)</h3>
-
-<h3>Jump to the first column of the current row (HOME, CTRL-A, CTRL-Left)</h3>
-
-<h3>Move the cursor one column to the left (&lt;)</h3>
-
-<h3>Move the cursor one column to the right (&gt;)</h3>
-
-<h3>Jump to the first row in the current column (CTRL-Up)</h3>
-
-<h3>Jump to the last row in the current column (CTRL-Down)</h3>
-
-</body>
-</html>
+<?xml version='1.0' encoding='iso-8859-1'?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link rel="stylesheet" href="igrid_help.css" type="text/css" />
+<title>igrid help</title>
+</head>
+<body>
+<h1>igrid help</h1>
+
+
+<h2>Commands</h2>
+
+
+<h3>pick (P)</h3>
+<p>Pick the whole row (object is available as "_")</p>
+
+<h3>pickattr (Shift-P)</h3>
+<p>Pick the attribute under the cursor</p>
+
+<h3>pickallattrs (Shift-C)</h3>
+<p>Pick' the complete column under the cursor (i.e. the attribute under the
+cursor) from all currently fetched objects. These attributes will be returned
+as a list.</p>
+
+<h3>enter (E)</h3>
+<p>Enter the object under the cursor. (what this mean depends on the object
+itself, i.e. how it implements iteration). This opens a new browser 'level'.</p>
+
+<h3>enterattr (Shift-E)</h3>
+<p>Enter the attribute under the cursor.</p>
+
+<h3>detail (D)</h3>
+<p>Show a detail view of the object under the cursor. This shows the name,
+type, doc string and value of the object attributes (and it might show more
+attributes than in the list view, depending on the object).</p>
+
+<h3>detailattr (Shift-D)</h3>
+<p>Show a detail view of the attribute under the cursor.</p>
+
+<h3>pickrows (M)</h3>
+<p>Pick multiple selected rows (M)</p>
+
+<h3>pickrowsattr (CTRL-M)</h3>
+<p>From multiple selected rows pick the cells matching the attribute the cursor is in (CTRL-M)</p>
+
+<h3>find (CTRL-F)</h3>
+<p>Find text</p>
+
+<h3>find_next (F3)</h3>
+<p>Find next occurrence of the searchtext</p>
+
+<h3>find_previous (Shift-F3)</h3>
+<p>Find previous occurrence of the searchtext </p>
+
+<h3>sortattrasc (V)</h3>
+<p>Sort the objects (in ascending order) using the attribute under the cursor as the sort key.</p>
+
+<h3>sortattrdesc (Shift-V)</h3>
+<p>Sort the objects (in descending order) using the attribute under the cursor as the sort key.</p>
+
+<h3>leave (Backspace, DEL, X)</h3>
+<p>Close current tab (and all the tabs to the right of the current one).</h3>
+
+<h3>quit (ESC,Q)</h3>
+<p>Quit igrid and return to the IPython prompt.</p>
+
+
+<h2>Navigation</h2>
+
+
+<h3>Jump to the last column of the current row (END, CTRL-E, CTRL-Right)</h3>
+
+<h3>Jump to the first column of the current row (HOME, CTRL-A, CTRL-Left)</h3>
+
+<h3>Move the cursor one column to the left (&lt;)</h3>
+
+<h3>Move the cursor one column to the right (&gt;)</h3>
+
+<h3>Jump to the first row in the current column (CTRL-Up)</h3>
+
+<h3>Jump to the last row in the current column (CTRL-Down)</h3>
+
+</body>
+</html>

IPython/Extensions/ipy_app_completers.py

@@ -14,4 +14,6 b' from ipy_completers import *'
 ip.set_hook('complete_command', apt_completer, re_key = '.*apt-get')
 ip.set_hook('complete_command', svn_completer, str_key = 'svn')
 ip.set_hook('complete_command', hg_completer, str_key = 'hg')
-ip.set_hook('complete_command', bzr_completer, str_key = 'bzr')
+
+# the old bzr completer is deprecated, we recommend ipy_bzr
+#ip.set_hook('complete_command', bzr_completer, str_key = 'bzr')

IPython/Extensions/ipy_completers.py

@@ -1,4 +1,3 b''
-#!/usr/bin/env python
 
 """ Implementations for various useful completers
 
@@ -12,6 +11,7 b' import IPython.ipapi'
 import glob,os,shlex,sys
 import inspect
 from time import time
+from zipimport import zipimporter
 ip = IPython.ipapi.get()
 
 try:
@@ -86,13 +86,18 b' def moduleList(path):'
 
     if os.path.isdir(path):
         folder_list = os.listdir(path)
+    elif path.endswith('.egg'):
+        try:
+            folder_list = [f for f in zipimporter(path)._files]
+        except:
+            folder_list = []
     else:
         folder_list = []
     #folder_list = glob.glob(os.path.join(path,'*'))
     folder_list = [p for p in folder_list  \
        if os.path.exists(os.path.join(path, p,'__init__.py'))\
            or p[-3:] in ('.py','.so')\
-           or p[-4:] in ('.pyc','.pyo')]
+           or p[-4:] in ('.pyc','.pyo','.pyd')]
 
     folder_list = [os.path.basename(p).split('.')[0] for p in folder_list]
     return folder_list
@@ -211,15 +216,15 b' def hg_completer(self,event):'
 
 
 
-bzr_commands = """
-add annotate bind branch break-lock bundle-revisions cat check
-checkout commit conflicts deleted diff export gannotate gbranch
-gcommit gdiff help ignore ignored info init init-repository inventory
-log merge missing mkdir mv nick pull push reconcile register-branch
-remerge remove renames resolve revert revno root serve sign-my-commits
-status testament unbind uncommit unknowns update upgrade version
-version-info visualise whoami
-"""
+__bzr_commands = None
+
+def bzr_commands():
+    global __bzr_commands
+    if __bzr_commands is not None:
+        return __bzr_commands
+    out = os.popen('bzr help commands')
+    __bzr_commands = [l.split()[0] for l in out]
+    return __bzr_commands                
 
 def bzr_completer(self,event):
     """ Completer for bazaar commands """
@@ -232,7 +237,7 b' def bzr_completer(self,event):'
         param = cmd_param[-1]
         output_file = (param == '--output=')
         if cmd == 'help':
-            return bzr_commands.split()
+            return bzr_commands()
         elif cmd in ['bundle-revisions','conflicts',
                      'deleted','nick','register-branch',
                      'serve','unbind','upgrade','version',
@@ -242,7 +247,7 b' def bzr_completer(self,event):'
             # the rest are probably file names
             return ip.IP.Completer.file_matches(event.symbol)
 
-    return bzr_commands.split()
+    return bzr_commands()
 
 
 def shlex_split(x):
@@ -326,7 +331,29 b' def cd_completer(self, event):'
         if os.path.isdir(relpath):
             return [relpath]
         raise IPython.ipapi.TryNext
-    return found
+
+
+    def single_dir_expand(matches):
+        "Recursively expand match lists containing a single dir."
+        
+        if len(matches) == 1 and os.path.isdir(matches[0]):
+            # Takes care of links to directories also.  Use '/'
+            # explicitly, even under Windows, so that name completions
+            # don't end up escaped.
+            d = matches[0]
+            if d[-1] in ['/','\\']:
+                d = d[:-1]
+
+            subdirs = [p for p in os.listdir(d) if os.path.isdir( d + '/' + p)]
+            if subdirs:
+                matches = [ (d + '/' + p) for p in subdirs ]
+                return single_dir_expand(matches)
+            else:
+                return matches
+        else:
+            return matches
+
+    return single_dir_expand(found)
 
 def apt_get_packages(prefix):
     out = os.popen('apt-cache pkgnames')

IPython/Extensions/ipy_leo.py

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

IPython/Extensions/ipy_profile_sh.py

@@ -43,11 +43,13 b' def main():'
     # %store foo
     # %store bar
     import ipy_rehashdir
-    import ipy_signals
+
+    # does not work without subprocess module!
+    #import ipy_signals
     
     ip.ex('import os')
     ip.ex("def up(): os.chdir('..')")
-        
+    ip.user_ns['LA'] = LastArgFinder() 
     # Nice prompt
     
     o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#> '
@@ -117,6 +119,29 b' def main():'
     
     extend_shell_behavior(ip)
 
+class LastArgFinder:
+    """ Allow $LA to work as "last argument of previous command", like $! in bash
+    
+    To call this in normal IPython code, do LA()
+    """
+    def __call__(self, hist_idx = None):
+        ip = ipapi.get()
+        if hist_idx is None:
+            return str(self)
+        return ip.IP.input_hist_raw[hist_idx].strip().split()[-1]
+    def __str__(self):
+        ip = ipapi.get()        
+        for cmd in reversed(ip.IP.input_hist_raw):
+            parts = cmd.strip().split()
+            if len(parts) < 2 or parts[-1] in ['$LA', 'LA()']:
+                continue
+            return parts[-1]
+        return ""
+
+
+
+
+
 # XXX You do not need to understand the next function!
 # This should probably be moved out of profile
 

IPython/Extensions/jobctrl.py

@@ -41,8 +41,9 b' Now launch a new IPython prompt and kill the process:'
 (you don't need to specify PID for %kill if only one task is running)
 """                     
 
-from subprocess import Popen,PIPE
+from subprocess import *
 import os,shlex,sys,time
+import threading,Queue
 
 from IPython import genutils
 
@@ -71,15 +72,70 b' def startjob(job):'
     p.line = job
     return p
 
+class AsyncJobQ(threading.Thread):
+    def __init__(self):
+        threading.Thread.__init__(self)
+        self.q = Queue.Queue()
+        self.output = []
+        self.stop = False
+    def run(self):
+        while 1:
+            cmd,cwd = self.q.get()
+            if self.stop:
+                self.output.append("** Discarding: '%s' - %s" % (cmd,cwd))
+                continue
+            self.output.append("** Task started: '%s' - %s" % (cmd,cwd))
+            
+            p = Popen(cmd, shell=True, stdout=PIPE, stderr=STDOUT, cwd = cwd)
+            out = p.stdout.read()
+            self.output.append("** Task complete: '%s'\n" % cmd)
+            self.output.append(out)
+
+    def add(self,cmd):
+        self.q.put_nowait((cmd, os.getcwd()))
+        
+    def dumpoutput(self):
+        while self.output:
+            item = self.output.pop(0)
+            print item            
+
+_jobq = None
+
+def jobqueue_f(self, line):
+     
+    global _jobq
+    if not _jobq:
+        print "Starting jobqueue - do '&some_long_lasting_system_command' to enqueue"
+        _jobq = AsyncJobQ()
+        _jobq.setDaemon(True)
+        _jobq.start()
+        ip.jobq = _jobq.add
+        return
+    if line.strip() == 'stop':
+        print "Stopping and clearing jobqueue, %jobqueue start to start again"
+        _jobq.stop = True
+        return
+    if line.strip() == 'start':
+        _jobq.stop = False
+        return
+        
 def jobctrl_prefilter_f(self,line):    
     if line.startswith('&'):
         pre,fn,rest = self.split_user_input(line[1:])
         
         line = ip.IP.expand_aliases(fn,rest)
-        return '_ip.startjob(%s)' % genutils.make_quoted_expr(line)
+        if not _jobq:
+            return '_ip.startjob(%s)' % genutils.make_quoted_expr(line)
+        return '_ip.jobq(%s)' % genutils.make_quoted_expr(line)
 
     raise IPython.ipapi.TryNext
 
+def jobq_output_hook(self):
+    if not _jobq:
+        return
+    _jobq.dumpoutput()
+
+
 
 def job_list(ip):
     keys = ip.db.keys('tasks/*')
@@ -91,8 +147,16 b' def magic_tasks(self,line):'
 
     A 'task' is a process that has been started in IPython when 'jobctrl' extension is enabled.
     Tasks can be killed with %kill.
+    
+    '%tasks clear' clears the task list (from stale tasks)
     """
     ip = self.getapi()
+    if line.strip() == 'clear':
+        for k in ip.db.keys('tasks/*'):
+            print "Clearing",ip.db[k]
+            del ip.db[k]
+        return
+        
     ents = job_list(ip)
     if not ents:
         print "No tasks running"
@@ -125,7 +189,7 b' def magic_kill(self,line):'
         magic_tasks(self,line)
         
 if sys.platform == 'win32':
-    shell_internal_commands = 'break chcp cls copy ctty date del erase dir md mkdir path prompt rd rmdir time 	type ver vol'.split()
+    shell_internal_commands = 'break chcp cls copy ctty date del erase dir md mkdir path prompt rd rmdir start time type ver vol'.split()
 else:
     # todo linux commands
     shell_internal_commands = [] 
@@ -133,20 +197,33 b' else:'
 
 def jobctrl_shellcmd(ip,cmd):
     """ os.system replacement that stores process info to db['tasks/t1234'] """
+    cmd = cmd.strip()
     cmdname = cmd.split(None,1)[0]
-    if cmdname in shell_internal_commands:
+    if cmdname in shell_internal_commands or '|' in cmd or '>' in cmd or '<' in cmd:
         use_shell = True
     else:
         use_shell = False
 
-    p = Popen(cmd,shell = use_shell)
-    jobentry = 'tasks/t' + str(p.pid)
-    
+    jobentry = None
     try:
+        try:
+            p = Popen(cmd,shell = use_shell)
+        except WindowsError:
+            if use_shell:
+                # try with os.system
+                os.system(cmd)
+                return
+            else:
+                # have to go via shell, sucks
+                p = Popen(cmd,shell = True)
+            
+        jobentry = 'tasks/t' + str(p.pid)
         ip.db[jobentry] = (p.pid,cmd,os.getcwd(),time.time())
-        p.communicate()
+        p.communicate()        
+
     finally:
-        del ip.db[jobentry]
+        if jobentry:
+            del ip.db[jobentry]
 
 
 def install():
@@ -158,5 +235,6 b' def install():'
     ip.set_hook('shell_hook', jobctrl_shellcmd)
     ip.expose_magic('kill',magic_kill)
     ip.expose_magic('tasks',magic_tasks)
-    
+    ip.expose_magic('jobqueue',jobqueue_f)
+    ip.set_hook('pre_prompt_hook', jobq_output_hook) 
 install()

IPython/Itpl.py

@@ -94,8 +94,16 b' def matchorfail(text, pos):'
     match = tokenprog.match(text, pos)
     if match is None:
         raise ItplError(text, pos)
+
     return match, match.end()
 
+try:
+    itpl_encoding = sys.stdin.encoding or 'ascii'
+except AttributeError:
+    itpl_encoding = 'ascii'
+
+    
+
 class Itpl:
     """Class representing a string with interpolation abilities.
     
@@ -104,7 +112,7 b' class Itpl:'
     evaluation and substitution happens in the namespace of the
     caller when str(instance) is called."""
 
-    def __init__(self, format,codec=sys.stdin.encoding,encoding_errors='backslashreplace'):
+    def __init__(self, format,codec=itpl_encoding,encoding_errors='backslashreplace'):
         """The single mandatory argument to this constructor is a format
         string.
 

IPython/Magic.py

@@ -115,9 +115,9 b' class Magic:'
 
     def profile_missing_notice(self, *args, **kwargs):
         error("""\
-The profile module could not be found.  If you are a Debian user,
-it has been removed from the standard Debian package because of its non-free
-license. To use profiling, please install"python2.3-profiler" from non-free.""")
+The profile module could not be found. It has been removed from the standard
+python packages because of its non-free license. To use profiling, install the
+python-profiler package from non-free.""")
 
     def default_option(self,fn,optstr):
         """Make an entry in the options_table for fn, with value optstr"""
@@ -147,7 +147,7 b' license. To use profiling, please install"python2.3-profiler" from non-free.""")'
                  filter(inst_magic,self.__dict__.keys()) + \
                  filter(inst_bound_magic,self.__class__.__dict__.keys())
         out = []
-        for fn in magics:
+        for fn in Set(magics):
             out.append(fn.replace('magic_','',1))
         out.sort()
         return out
@@ -386,7 +386,10 b' license. To use profiling, please install"python2.3-profiler" from non-free.""")'
         return None
         
     def magic_magic(self, parameter_s = ''):
-        """Print information about the magic function system."""
+        """Print information about the magic function system.
+        
+        Supported formats: -latex, -brief, -rest        
+        """
 
         mode = ''
         try:
@@ -394,6 +397,9 b' license. To use profiling, please install"python2.3-profiler" from non-free.""")'
                 mode = 'latex'
             if parameter_s.split()[0] == '-brief':
                 mode = 'brief'
+            if parameter_s.split()[0] == '-rest':
+                mode = 'rest'
+                rest_docs = []
         except:
             pass
 
@@ -409,14 +415,26 b' license. To use profiling, please install"python2.3-profiler" from non-free.""")'
                     break
             if mode == 'brief':
                 # only first line
-                fndoc = fn.__doc__.split('\n',1)[0]
+                if fn.__doc__:                    
+                    fndoc = fn.__doc__.split('\n',1)[0]
+                else:
+                    fndoc = 'No documentation'
+            else:
+                fndoc = fn.__doc__.rstrip()
+                
+            if mode == 'rest':
+                rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
+                                                    fname,fndoc))
+                
             else:
-                fndoc = fn.__doc__
+                magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
+                                                    fname,fndoc))
                 
-            magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
-                                                fname,fndoc))
         magic_docs = ''.join(magic_docs)
 
+        if mode == 'rest':
+            return "".join(rest_docs)
+        
         if mode == 'latex':
             print self.format_latex(magic_docs)
             return
@@ -2612,7 +2630,7 b' Defaulting color scheme to \'NoColor\'"""'
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         base, ext = os.path.splitext(ff)
-                        if isexec(ff) and base not in self.shell.no_alias:
+                        if isexec(ff) and base.lower() not in self.shell.no_alias:
                             if ext.lower() == '.exe':
                                 ff = base
                             alias_table[base.lower()] = (0,ff)
@@ -2667,6 +2685,7 b' Defaulting color scheme to \'NoColor\'"""'
         parameter_s = parameter_s.strip()
         #bkms = self.shell.persist.get("bookmarks",{})
 
+        oldcwd = os.getcwd()
         numcd = re.match(r'(-)(\d+)$',parameter_s)
         # jump in directory history by number
         if numcd:
@@ -2705,7 +2724,7 b' Defaulting color scheme to \'NoColor\'"""'
             
         # at this point ps should point to the target dir
         if ps:
-            try:
+            try:                
                 os.chdir(os.path.expanduser(ps))
                 if self.shell.rc.term_title:
                     #print 'set term title:',self.shell.rc.term_title  # dbg
@@ -2716,8 +2735,9 b' Defaulting color scheme to \'NoColor\'"""'
             else:
                 cwd = os.getcwd()
                 dhist = self.shell.user_ns['_dh']
-                dhist.append(cwd)
-                self.db['dhist'] = compress_dhist(dhist)[-100:]
+                if oldcwd != cwd:
+                    dhist.append(cwd)
+                    self.db['dhist'] = compress_dhist(dhist)[-100:]
                 
         else:
             os.chdir(self.shell.home_dir)
@@ -2725,8 +2745,10 b' Defaulting color scheme to \'NoColor\'"""'
                 platutils.set_term_title("IPy ~")
             cwd = os.getcwd()
             dhist = self.shell.user_ns['_dh']
-            dhist.append(cwd)
-            self.db['dhist'] = compress_dhist(dhist)[-100:]
+            
+            if oldcwd != cwd:
+                dhist.append(cwd)
+                self.db['dhist'] = compress_dhist(dhist)[-100:]
         if not 'q' in opts and self.shell.user_ns['_dh']:
             print self.shell.user_ns['_dh'][-1]
 
@@ -3118,7 +3140,7 b' Defaulting color scheme to \'NoColor\'"""'
              screen_lines=self.shell.rc.screen_length)
 
     def magic_cpaste(self, parameter_s=''):
-        """Allows you to paste & execute a pre-formatted code block from clipboard
+        """Allows you to paste & execute a pre-formatted code block from clipboard.
         
         You must terminate the block with '--' (two minus-signs) alone on the
         line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
@@ -3126,13 +3148,14 b' Defaulting color scheme to \'NoColor\'"""'
         
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
-        ignored, to allow pasting directly from e-mails or diff files. The
+        ignored, to allow pasting directly from e-mails, diff files and
+        doctests (the '...' continuation prompt is also stripped).  The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
         
         You can also pass a variable name as an argument, e.g. '%cpaste foo'.
         This assigns the pasted block to variable 'foo' as string, without 
-        dedenting or executing it.
+        dedenting or executing it (preceding >>> and + is still stripped)
         
         Do not be alarmed by garbled output on Windows (it's a readline bug). 
         Just press enter and type -- (and press enter again) and the block 
@@ -3143,6 +3166,15 b' Defaulting color scheme to \'NoColor\'"""'
         opts,args = self.parse_options(parameter_s,'s:',mode='string')
         par = args.strip()
         sentinel = opts.get('s','--')
+
+        # Regular expressions that declare text we strip from the input:
+        strip_re =  [r'^\s*In \[\d+\]:', # IPython input prompt
+                     r'^\s*(\s?>)+', # Python input prompt
+                     r'^\s*\.{3,}', # Continuation prompts
+                     r'^\++',
+                     ]
+
+        strip_from_start = map(re.compile,strip_re)
         
         from IPython import iplib
         lines = []
@@ -3151,7 +3183,11 b' Defaulting color scheme to \'NoColor\'"""'
             l = iplib.raw_input_original(':')
             if l ==sentinel:
                 break
-            lines.append(l.lstrip('>').lstrip('+'))
+            
+            for pat in strip_from_start: 
+                l = pat.sub('',l)
+            lines.append(l)
+                         
         block = "\n".join(lines) + '\n'
         #print "block:\n",block
         if not par:

IPython/OInspect.py

@@ -404,7 +404,13 b' class Inspector:'
         # Filename where object was defined
         binary_file = False
         try:
-            fname = inspect.getabsfile(obj)
+            try:
+                fname = inspect.getabsfile(obj)
+            except TypeError:
+                # For an instance, the file that matters is where its class was
+                # declared.
+                if hasattr(obj,'__class__'):
+                    fname = inspect.getabsfile(obj.__class__)
             if fname.endswith('<string>'):
                 fname = 'Dynamically generated function. No source code available.'
             if (fname.endswith('.so') or fname.endswith('.dll')):
@@ -432,8 +438,13 b' class Inspector:'
             linecache.checkcache()
             source_success = False
             try:
-                source = self.format(getsource(obj,binary_file))
-                if source:
+                try:
+                    src = getsource(obj,binary_file)
+                except TypeError:
+                    if hasattr(obj,'__class__'):
+                        src = getsource(obj.__class__,binary_file)
+                if src is not None:
+                    source = self.format(src)
                     out.write(header('Source:\n')+source.rstrip())
                     source_success = True
             except Exception, msg:

IPython/Release.py

@@ -22,9 +22,15 b" name = 'ipython'"
 # because bdist_rpm does not accept dashes (an RPM) convention, and
 # bdist_deb does not accept underscores (a Debian convention).
 
-revision = '3001'
+revision = '128'
+branch = 'ipython'
 
-version = '0.8.3.svn.r' + revision.rstrip('M')
+if branch == 'ipython':
+    version = '0.8.4.bzr.r' + revision
+else:
+    version = '0.8.4.bzr.r%s.%s'  % (revision,branch)
+
+version = '0.8.4'
 
 description = "An enhanced interactive Python shell."
 

IPython/Shell.py

@@ -46,6 +46,13 b' from IPython.ipmaker import make_IPython'
 from IPython.Magic import Magic
 from IPython.ipstruct import Struct
 
+try: # Python 2.3 compatibility
+    set
+except NameError:
+    import sets
+    set = sets.Set
+
+
 # Globals
 # global flag to pass around information about Ctrl-C without exceptions
 KBINT = False
@@ -358,36 +365,37 b' class MTInteractiveShell(InteractiveShell):'
         InteractiveShell.__init__(self,name,usage,rc,user_ns,
                                   user_global_ns,banner2)
 
-        # Locking control variable.
-        self.thread_ready = threading.Condition(threading.RLock())
 
-        # A queue to hold the code to be executed.  A scalar variable is NOT
-        # enough, because uses like macros cause reentrancy.
+        # A queue to hold the code to be executed. 
         self.code_queue = Queue.Queue()
 
         # Stuff to do at closing time
-        self._kill = False
-        on_kill = kw.get('on_kill')
-        if on_kill is None:
-            on_kill = []
+        self._kill = None
+        on_kill = kw.get('on_kill', [])
         # Check that all things to kill are callable:
         for t in on_kill:
             if not callable(t):
                 raise TypeError,'on_kill must be a list of callables'
         self.on_kill = on_kill
-
+        # thread identity of the "worker thread" (that may execute code directly)
+        self.worker_ident = None
+        
     def runsource(self, source, filename="<input>", symbol="single"):
         """Compile and run some source in the interpreter.
 
         Modified version of code.py's runsource(), to handle threading issues.
         See the original for full docstring details."""
-
+        
         global KBINT
         
         # If Ctrl-C was typed, we reset the flag and return right away
         if KBINT:
             KBINT = False
             return False
+
+        if self._kill:
+            # can't queue new code if we are being killed
+            return True
         
         try:
             code = self.compile(source, filename, symbol)
@@ -400,29 +408,40 b' class MTInteractiveShell(InteractiveShell):'
             # Case 2
             return True
 
+        # shortcut - if we are in worker thread, or the worker thread is not running, 
+        # execute directly (to allow recursion and prevent deadlock if code is run early 
+        # in IPython construction)
+        
+        if (self.worker_ident is None or self.worker_ident == thread.get_ident()):
+            InteractiveShell.runcode(self,code)
+            return
+
         # Case 3
         # Store code in queue, so the execution thread can handle it.
 
-        # Note that with macros and other applications, we MAY re-enter this
-        # section, so we have to acquire the lock with non-blocking semantics,
-        # else we deadlock.
-        got_lock = self.thread_ready.acquire()
-        self.code_queue.put(code)
-        if got_lock:
-           self.thread_ready.wait()  # Wait until processed in timeout interval
-        self.thread_ready.release()
-
+        completed_ev, received_ev = threading.Event(), threading.Event() 
+        
+        self.code_queue.put((code,completed_ev, received_ev))
+        # first make sure the message was received, with timeout
+        received_ev.wait(5)
+        if not received_ev.isSet():
+            # the mainloop is dead, start executing code directly
+            print "Warning: Timeout for mainloop thread exceeded"
+            print "switching to nonthreaded mode (until mainloop wakes up again)"
+            self.worker_ident = None
+        else:
+            completed_ev.wait()
         return False
 
     def runcode(self):
         """Execute a code object.
 
         Multithreaded wrapper around IPython's runcode()."""
-
+        
         global CODE_RUN
-
-        # lock thread-protected stuff
-        got_lock = self.thread_ready.acquire()
+        
+        # we are in worker thread, stash out the id for runsource() 
+        self.worker_ident = thread.get_ident()
 
         if self._kill:
             print >>Term.cout, 'Closing threads...',
@@ -430,6 +449,9 b' class MTInteractiveShell(InteractiveShell):'
             for tokill in self.on_kill:
                 tokill()
             print >>Term.cout, 'Done.'
+            # allow kill() to return
+            self._kill.set()
+            return True
 
         # Install sigint handler.  We do it every time to ensure that if user
         # code modifies it, we restore our own handling.
@@ -445,10 +467,11 b' class MTInteractiveShell(InteractiveShell):'
         code_to_run = None
         while 1:
             try:
-                code_to_run = self.code_queue.get_nowait()
+                code_to_run, completed_ev, received_ev = self.code_queue.get_nowait()                
             except Queue.Empty:
                 break
-
+            received_ev.set()
+            
             # Exceptions need to be raised differently depending on which
             # thread is active.  This convoluted try/except is only there to
             # protect against asynchronous exceptions, to ensure that a KBINT
@@ -462,28 +485,23 b' class MTInteractiveShell(InteractiveShell):'
                 except KeyboardInterrupt:
                    print "Keyboard interrupted in mainloop"
                    while not self.code_queue.empty():
-                      self.code_queue.get_nowait()
+                      code, ev1,ev2 = self.code_queue.get_nowait()
+                      ev1.set()
+                      ev2.set()                      
                    break
             finally:
-               if got_lock:
-                  CODE_RUN = False
-
-        # We're done with thread-protected variables
-        if code_to_run is not None:
-           self.thread_ready.notify()
-        self.thread_ready.release()
-
-        # We're done...
-        CODE_RUN = False
+                CODE_RUN = False
+                # allow runsource() return from wait
+                completed_ev.set()
+                
+        
         # This MUST return true for gtk threading to work
         return True
 
     def kill(self):
         """Kill the thread, returning when it has been shut down."""
-        got_lock = self.thread_ready.acquire(False)
-        self._kill = True
-        if got_lock:
-            self.thread_ready.release()
+        self._kill = threading.Event()
+        self._kill.wait()
 
 class MatplotlibShellBase:
     """Mixin class to provide the necessary modifications to regular IPython
@@ -1051,7 +1069,9 b' def _load_pylab(user_ns):'
     
     ip = IPython.ipapi.get()
     if ip.options.pylab_import_all:
-        exec "from matplotlib.pylab import *" in user_ns
+        ip.ex("from matplotlib.pylab import *")
+        ip.IP.user_config_ns.update(ip.user_ns)
+        
 
 class IPShellMatplotlib(IPShell):
     """Subclass IPShell with MatplotlibShell as the internal shell.
@@ -1144,7 +1164,7 b' def _select_shell(argv):'
     all_opts = set(['tk','pylab','gthread','qthread','q4thread','wthread',
                     'tkthread'])
     user_opts = set([s.replace('-','') for s in argv[:3]])
-    special_opts = user_opts & all_opts
+    special_opts = user_opts & all_opts            
 
     if 'tk' in special_opts:
         USE_TK = True

IPython/UserConfig/ipy_user_conf.py

@@ -72,6 +72,27 b' def main():'
     #o.autoexec.append('%colors NoColor')
     #o.autoexec.append('%colors Linux')
     
+    # for sane integer division that converts to float (1/2 == 0.5)
+    #o.autoexec.append('from __future__ import division')
+    
+    # For %tasks and %kill
+    #import jobctrl 
+    
+    # For autoreloading of modules (%autoreload, %aimport)    
+    #import ipy_autoreload
+    
+    # For winpdb support (%wdb)
+    #import ipy_winpdb
+    
+    # For bzr completer, requires bzrlib (the python installation of bzr)
+    #ip.load('ipy_bzr')
+    
+    # Tab completer that is not quite so picky (i.e. 
+    # "foo".<TAB> and str(2).<TAB> will work). Complete 
+    # at your own risk!
+    #import ipy_greedycompleter
+    
+    
     
 # some config helper functions you can use 
 def import_all(modules):

IPython/completer.py

@@ -321,7 +321,7 b' class IPCompleter(Completer):'
         # don't want to treat as delimiters in filename matching
         # when escaped with backslash
 
-        protectables = ' ()[]{}'
+        protectables = ' '
 
         if text.startswith('!'):
             text = text[1:]

IPython/deep_reload.py

@@ -32,7 +32,9 b' import imp'
 import sys
 
 # Replacement for __import__()
-def deep_import_hook(name, globals=None, locals=None, fromlist=None):
+def deep_import_hook(name, globals=None, locals=None, fromlist=None, level=-1):
+    # For now level is ignored, it's just there to prevent crash  
+    # with from __future__ import absolute_import
     parent = determine_parent(globals)
     q, tail = find_head_package(parent, name)
     m = load_tail(q, tail)

IPython/external/mglob.py

@@ -34,35 +34,35 b' License: MIT Open Source license'
 #Assigned in variable for "usage" printing convenience"
 
 globsyntax = """\
-This program allows specifying filenames with "mglob" mechanism.
-Supported syntax in globs (wilcard matching patterns)::
-
- *.cpp ?ellowo*                
-     - obvious. Differs from normal glob in that dirs are not included.
-       Unix users might want to write this as: "*.cpp" "?ellowo*"
- rec:/usr/share=*.txt,*.doc    
-     - get all *.txt and *.doc under /usr/share, 
-       recursively
- rec:/usr/share
-     - All files under /usr/share, recursively
- rec:*.py
-     - All .py files under current working dir, recursively
- foo                           
-     - File or dir foo
- !*.bak readme*                   
-     - readme*, exclude files ending with .bak
- !.svn/ !.hg/ !*_Data/ rec:.
-     - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
-       Trailing / is the key, \ does not work!
- dir:foo                       
-     - the directory foo if it exists (not files in foo)
- dir:*                         
-     - all directories in current folder
- foo.py bar.* !h* rec:*.py
-     - Obvious. !h* exclusion only applies for rec:*.py.
-       foo.py is *not* included twice.
- @filelist.txt
-     - All files listed in 'filelist.txt' file, on separate lines.
+    This program allows specifying filenames with "mglob" mechanism.
+    Supported syntax in globs (wilcard matching patterns)::
+    
+     *.cpp ?ellowo*                
+         - obvious. Differs from normal glob in that dirs are not included.
+           Unix users might want to write this as: "*.cpp" "?ellowo*"
+     rec:/usr/share=*.txt,*.doc    
+         - get all *.txt and *.doc under /usr/share, 
+           recursively
+     rec:/usr/share
+         - All files under /usr/share, recursively
+     rec:*.py
+         - All .py files under current working dir, recursively
+     foo                           
+         - File or dir foo
+     !*.bak readme*                   
+         - readme*, exclude files ending with .bak
+     !.svn/ !.hg/ !*_Data/ rec:.
+         - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
+           Trailing / is the key, \ does not work!
+     dir:foo                       
+         - the directory foo if it exists (not files in foo)
+     dir:*                         
+         - all directories in current folder
+     foo.py bar.* !h* rec:*.py
+         - Obvious. !h* exclusion only applies for rec:*.py.
+           foo.py is *not* included twice.
+     @filelist.txt
+         - All files listed in 'filelist.txt' file, on separate lines.
  """
 
 

IPython/external/path.py

@@ -29,7 +29,10 b' Date: 9 Mar 2007'
 
 from __future__ import generators
 
-import sys, warnings, os, fnmatch, glob, shutil, codecs, md5
+import sys, warnings, os, fnmatch, glob, shutil, codecs
+# deprecated in python 2.6
+warnings.filterwarnings('ignore', r'.*md5.*')
+import md5
 
 __version__ = '2.2'
 __all__ = ['path']

IPython/genutils.py

@@ -22,7 +22,10 b' __license__ = Release.license'
 # required modules from the Python standard library
 import __main__
 import commands
-import doctest
+try:
+    import doctest
+except ImportError:
+    pass
 import os
 import re
 import shlex
@@ -33,6 +36,18 b' import time'
 import types
 import warnings
 
+# Curses and termios are Unix-only modules
+try:
+    import curses
+    # We need termios as well, so if its import happens to raise, we bail on
+    # using curses altogether.
+    import termios
+except ImportError:
+    USE_CURSES = False
+else:
+    # Curses on Solaris may not be complete, so we can't use it there
+    USE_CURSES = hasattr(curses,'initscr')
+
 # Other IPython utilities
 import IPython
 from IPython.Itpl import Itpl,itpl,printpl
@@ -1052,25 +1067,40 b' class SList(list):'
     
     p = paths = property(get_paths)
 
-    def grep(self, pattern, prune = False):
+    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(el)])
+            return SList([el for el in self if pred(match_target(el))])
         else:
-            return SList([el for el in self if not pred(el)])
+            return SList([el for el in self if not pred(match_target(el))])
     def fields(self, *fields):
         """ Collect whitespace-separated fields from string list
         
@@ -1083,6 +1113,7 b' class SList(list):'
         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.
         
@@ -1532,26 +1563,30 b' def page(strng,start=0,screen_lines=0,pager_cmd = None):'
     # auto-determine screen size
     if screen_lines <= 0:
         if TERM=='xterm':
-            try:
-                import curses
-                if hasattr(curses,'initscr'):
-                    use_curses = 1
-                else:
-                    use_curses = 0
-            except ImportError:
-                use_curses = 0
+            use_curses = USE_CURSES
         else:
             # curses causes problems on many terminals other than xterm.
-            use_curses = 0
+            use_curses = False
         if use_curses:
-                scr = curses.initscr()
-                screen_lines_real,screen_cols = scr.getmaxyx()
-                curses.endwin()
-                screen_lines += screen_lines_real
-                #print '***Screen size:',screen_lines_real,'lines x',\
-                #screen_cols,'columns.' # dbg
+            # There is a bug in curses, where *sometimes* it fails to properly
+            # initialize, and then after the endwin() call is made, the
+            # terminal is left in an unusable state.  Rather than trying to
+            # check everytime for this (by requesting and comparing termios
+            # flags each time), we just save the initial terminal state and
+            # unconditionally reset it every time.  It's cheaper than making
+            # the checks.
+            term_flags = termios.tcgetattr(sys.stdout)
+            scr = curses.initscr()
+            screen_lines_real,screen_cols = scr.getmaxyx()
+            curses.endwin()
+            # Restore terminal state in case endwin() didn't.
+            termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
+            # Now we have what we needed: the screen size in rows/columns
+            screen_lines += screen_lines_real
+            #print '***Screen size:',screen_lines_real,'lines x',\
+            #screen_cols,'columns.' # dbg
         else:
-                screen_lines += screen_lines_def
+            screen_lines += screen_lines_def
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :

IPython/gui/wx/ipython_history.py

@@ -28,10 +28,30 b' class IPythonHistoryPanel(wx.Panel):'
         self.filter_cmd   = wx.CheckBox(self, -1, "!: Sys commands")
         self.filter_magic = wx.CheckBox(self, -1, "%: Magic keys")
 
-        self.filter_empty.SetValue(flt_empty)
-        self.filter_doc.SetValue(flt_doc)
-        self.filter_cmd.SetValue(flt_cmd)
-        self.filter_magic.SetValue(flt_magic)
+        self.options={'filter_empty':{'value':'True',
+                                      'checkbox':self.filter_empty,'True':True,'False':False,
+                                      'setfunc':lambda x:None},
+                      'filter_doc':{'value':'True',
+                                    'checkbox':self.filter_doc,'True':True,'False':False,
+                                    'setfunc':lambda x:None},
+                      'filter_cmd':{'value':'True',
+                                    'checkbox':self.filter_cmd,'True':True,'False':False,
+                                    'setfunc':lambda x:None},
+                      'filter_magic':{'value':'True',
+                                      'checkbox':self.filter_magic,'True':True,'False':False,
+                                      'setfunc':lambda x:None},
+                     }
+        self.reloadOptions(self.options)
+
+        self.filter_empty.Bind(wx.EVT_CHECKBOX, self.evtCheckEmptyFilter)
+        self.filter_doc.Bind(wx.EVT_CHECKBOX, self.evtCheckDocFilter)
+        self.filter_cmd.Bind(wx.EVT_CHECKBOX, self.evtCheckCmdFilter)
+        self.filter_magic.Bind(wx.EVT_CHECKBOX, self.evtCheckMagicFilter)
+        
+        #self.filter_empty.SetValue(flt_empty)
+        #self.filter_doc.SetValue(flt_doc)
+        #self.filter_cmd.SetValue(flt_cmd)
+        #self.filter_magic.SetValue(flt_magic)
         
         sizer = wx.BoxSizer(wx.VERTICAL)
 
@@ -70,10 +90,54 b' class IPythonHistoryPanel(wx.Panel):'
                 add = False
             if self.filter_magic.GetValue() == True and history_line[0] == '%':
                 add = False
-	if add:
-        	self.text_ctrl.AppendText(history_line+'\n')
+        if add:
+                self.text_ctrl.AppendText(history_line+'\n')
+
+#------------------------ Option Section -----------------------------------
+    def processOptionCheckedEvt(self, event, name):
+        if event.IsChecked():
+            self.options[name]['value']='True'
+        else:
+            self.options[name]['value']='False'
+        self.updateOptionTracker(name,
+                                 self.options[name]['value'])
+        
+    def evtCheckEmptyFilter(self, event):
+        self.processOptionCheckedEvt(event, 'filter_empty')
+        
+    def evtCheckDocFilter(self, event):
+        self.processOptionCheckedEvt(event, 'filter_doc')
 
+    def evtCheckCmdFilter(self, event):
+        self.processOptionCheckedEvt(event, 'filter_cmd')
 
+    def evtCheckMagicFilter(self, event):
+        self.processOptionCheckedEvt(event, 'filter_magic')
+        
+    def getOptions(self):
+        return self.options
+    
+    def reloadOptions(self,options):
+        self.options = options
+        for key in self.options.keys():
+            value = self.options[key]['value']
+            self.options[key]['checkbox'].SetValue(self.options[key][value])
+            self.options[key]['setfunc'](value)
+
+#------------------------ Hook Section -----------------------------------
+    def updateOptionTracker(self,name,value):
+        '''
+        Default history tracker (does nothing)
+        '''
+        pass
+    
+    def setOptionTrackerHook(self,func):
+        '''
+        Define a new history tracker
+        '''
+        self.updateOptionTracker = func
+
+            
 #----------------------------------------------------------------------
 # Font definition for Styled Text Control
 

IPython/gui/wx/ipython_view.py

@@ -1,7 +1,7 b''
 #!/usr/bin/python
 # -*- coding: iso-8859-15 -*-
 '''
-Provides IPython WX console widget.
+Provides IPython WX console widgets.
 
 @author: Laurent Dufrechou
 laurent.dufrechou _at_ gmail.com
@@ -26,433 +26,88 b' __license__ = "BSD"'
 
 import wx
 import wx.stc  as  stc
-import wx.lib.newevent
 
 import re
 import sys
-import os
 import locale
-import time
-from ThreadEx import Thread
 from StringIO import StringIO
-
 try:
         import IPython
 except Exception,e:
         raise "Error importing IPython (%s)" % str(e)
 
-class IterableIPShell(Thread):
+from ipshell_nonblocking import NonBlockingIPShell
+
+class WxNonBlockingIPShell(NonBlockingIPShell):
     '''
-    Create an IPython instance inside a dedicated thread.
-    Does not start a blocking event loop, instead allow single iterations.
-    This allows embedding in any GUI without blockage.
-    The thread is a slave one, in that it doesn't interact directly with the GUI.
-    Note Thread class comes from ThreadEx that supports asynchroneous function call
-    via raise_exc()
+    An NonBlockingIPShell Thread that is WX dependent.
     '''
-
-    def __init__(self,argv=[],user_ns=None,user_global_ns=None,
+    def __init__(self, parent, 
+                 argv=[],user_ns={},user_global_ns=None,
                  cin=None, cout=None, cerr=None,
-                 exit_handler=None,time_loop = 0.1):
-        '''
-        @param argv: Command line options for IPython
-        @type argv: list
-        @param user_ns: User namespace.
-        @type user_ns: dictionary
-        @param user_global_ns: User global namespace.
-        @type user_global_ns: dictionary.
-        @param cin: Console standard input.
-        @type cin: IO stream
-        @param cout: Console standard output.
-        @type cout: IO stream
-        @param cerr: Console standard error.
-        @type cerr: IO stream
-        @param exit_handler: Replacement for builtin exit() function
-        @type exit_handler: function
-        @param time_loop: Define the sleep time between two thread's loop
-        @type int
-        '''
-        Thread.__init__(self)
-
-        #first we redefine in/out/error functions of IPython 
-        if cin:
-            IPython.Shell.Term.cin = cin
-        if cout:
-            IPython.Shell.Term.cout = cout
-        if cerr:
-            IPython.Shell.Term.cerr = cerr
-        
-        # This is to get rid of the blockage that accurs during
-        # IPython.Shell.InteractiveShell.user_setup()
-        IPython.iplib.raw_input = lambda x: None
-
-        self._term = IPython.genutils.IOTerm(cin=cin, cout=cout, cerr=cerr)
-
-        excepthook = sys.excepthook
-        self._IP = IPython.Shell.make_IPython(
-                                            argv,user_ns=user_ns,
-                                            user_global_ns=user_global_ns,
-                                            embedded=True,
-                                            shell_class=IPython.Shell.InteractiveShell)
-
-        #we replace IPython default encoding by wx locale encoding
-	loc = locale.getpreferredencoding()
-	if loc:
-        	self._IP.stdin_encoding = loc
-        #we replace the ipython default pager by our pager
-        self._IP.set_hook('show_in_pager',self._pager)
-        
-        #we replace the ipython default shell command caller by our shell handler
-	self._IP.set_hook('shell_hook',self._shell)
-        
-        #we replace the ipython default input command caller by our method
-        IPython.iplib.raw_input_original = self._raw_input
-        #we replace the ipython default exit command by our method
-        self._IP.exit = self._setAskExit
-            
-        sys.excepthook = excepthook
-
-        self._iter_more = 0
-        self._history_level = 0
-        self._complete_sep =  re.compile('[\s\{\}\[\]\(\)]')
-        self._prompt = str(self._IP.outputcache.prompt1).strip()
-
-        #thread working vars
-        self._terminate = False
-        self._time_loop = time_loop
-        self._has_doc = False
-        self._do_execute = False
-        self._line_to_execute = ''
-        self._doc_text = None
-        self._ask_exit = False
-
-    #----------------------- Thread management section ----------------------    
-    def run (self):
-        """
-        Thread main loop
-        The thread will run until self._terminate will be set to True via shutdown() function
-        Command processing can be interrupted with Instance.raise_exc(KeyboardInterrupt) call in the
-        GUI thread.
-        """
-        while(not self._terminate):
-            try:
-                if self._do_execute:
-                    self._doc_text = None
-                    self._execute()
-                    self._do_execute = False
-                
-            except KeyboardInterrupt:
-                pass
-
-            time.sleep(self._time_loop)
-            
-    def shutdown(self): 
-        """
-        Shutdown the tread
-        """
-        self._terminate = True
-
-    def doExecute(self,line):
-        """
-        Tell the thread to process the 'line' command
-        """
-        self._do_execute = True
-        self._line_to_execute = line
-        
-    def isExecuteDone(self):
-        """
-        Returns the processing state
-        """
-        return not self._do_execute
-
-    #----------------------- IPython management section ----------------------    
-    def getAskExit(self):
-        '''
-        returns the _ask_exit variable that can be checked by GUI to see if
-        IPython request an exit handling
-        '''
-        return self._ask_exit
-
-    def clearAskExit(self):
-        '''
-        clear the _ask_exit var when GUI as handled the request.
-        '''
-        self._ask_exit = False
-        
-    def getDocText(self):
-        """
-        Returns the output of the processing that need to be paged (if any)
-
-        @return: The std output string.
-        @rtype: string
-        """
-        return self._doc_text
-        
-    def getBanner(self):
-        """
-        Returns the IPython banner for useful info on IPython instance
-
-        @return: The banner string.
-        @rtype: string
-        """
-        return self._IP.BANNER
-    
-    def getPromptCount(self):
-        """
-        Returns the prompt number.
-        Each time a user execute a line in the IPython shell the prompt count is increased
-
-        @return: The prompt number
-        @rtype: int
-        """
-        return self._IP.outputcache.prompt_count
-
-    def getPrompt(self):
-        """
-        Returns current prompt inside IPython instance
-        (Can be In [...]: ot ...:)
-
-        @return: The current prompt.
-        @rtype: string
-        """
-        return self._prompt
-
-    def getIndentation(self):
-        """
-        Returns the current indentation level
-        Usefull to put the caret at the good start position if we want to do autoindentation.
-
-        @return: The indentation level.
-        @rtype: int
-        """
-        return self._IP.indent_current_nsp
+                 ask_exit_handler=None):
         
-    def updateNamespace(self, ns_dict):
-        '''
-        Add the current dictionary to the shell namespace.
+        NonBlockingIPShell.__init__(self,argv,user_ns,user_global_ns,
+                                    cin, cout, cerr,
+                                    ask_exit_handler)
 
-        @param ns_dict: A dictionary of symbol-values.
-        @type ns_dict: dictionary
-        '''
-        self._IP.user_ns.update(ns_dict)
+        self.parent = parent
 
-    def complete(self, line):
-        '''
-        Returns an auto completed line and/or posibilities for completion.
+        self.ask_exit_callback = ask_exit_handler
+        self._IP.exit = self._askExit
 
-        @param line: Given line so far.
-        @type line: string
+    def addGUIShortcut(self,text,func):
+        wx.CallAfter(self.parent.add_button_handler, 
+                button_info={   'text':text, 
+                                'func':self.parent.doExecuteLine(func)})
 
-        @return: Line completed as for as possible,
-        and possible further completions.
-        @rtype: tuple
-        '''
-        split_line = self._complete_sep.split(line)
-        possibilities = self._IP.complete(split_line[-1])
-        if possibilities:
-
-            def _commonPrefix(str1, str2):
-                '''
-                Reduction function. returns common prefix of two given strings.
-
-                @param str1: First string.
-                @type str1: string
-                @param str2: Second string
-                @type str2: string
-
-                @return: Common prefix to both strings.
-                @rtype: string
-                '''
-                for i in range(len(str1)):
-                    if not str2.startswith(str1[:i+1]):
-                        return str1[:i]
-                return str1
-            common_prefix = reduce(_commonPrefix, possibilities)
-            completed = line[:-len(split_line[-1])]+common_prefix
-        else:
-            completed = line
-        return completed, possibilities
+    def _askExit(self):
+        wx.CallAfter(self.ask_exit_callback, ())
 
-    def historyBack(self):
-        '''
-        Provides one history command back.
+    def _afterExecute(self):
+        wx.CallAfter(self.parent.evtStateExecuteDone, ())
 
-        @return: The command string.
-        @rtype: string
-        '''
-        history = ''
-        #the below while loop is used to suppress empty history lines
-	while((history == '' or history == '\n') and self._history_level >0):
-		if self._history_level>=1:
-			self._history_level -= 1
-		history = self._getHistory()		
-        return history
-
-    def historyForward(self):
-        '''
-        Provides one history command forward.
-
-        @return: The command string.
-        @rtype: string
-        '''
-	history = ''
-	#the below while loop is used to suppress empty history lines
-	while((history == '' or history == '\n') and self._history_level <= self._getHistoryMaxIndex()):
-		if self._history_level < self._getHistoryMaxIndex():
-			self._history_level += 1
-			history = self._getHistory()
-		else:
-			if self._history_level == self._getHistoryMaxIndex():
-				history = self._getHistory()
-				self._history_level += 1
-			else:
-				history = ''
-        return history
-
-    def initHistoryIndex(self):
-        '''
-        set history to last command entered
-        '''
-        self._history_level = self._getHistoryMaxIndex()+1
-
-    #----------------------- IPython PRIVATE management section ----------------------    
-    def _setAskExit(self):
-        '''
-        set the _ask_exit variable that can be cjhecked by GUI to see if
-        IPython request an exit handling
-        '''
-        self._ask_exit = True
-        
-    def _getHistoryMaxIndex(self):
-        '''
-        returns the max length of the history buffer
-
-        @return: history length
-        @rtype: int
-        '''
-        return len(self._IP.input_hist_raw)-1
-        
-    def _getHistory(self):
-        '''
-        Get's the command string of the current history level.
-
-        @return: Historic command string.
-        @rtype: string
-        '''
-        rv = self._IP.input_hist_raw[self._history_level].strip('\n')
-        return rv
-
-    def _pager(self,IP,text):
-        '''
-        This function is used as a callback replacment to IPython pager function
-
-        It puts the 'text' value inside the self._doc_text string that can be retrived via getDocText
-        function.
-        '''
-        self._doc_text = text
-    
-    def _raw_input(self, prompt=''):
-        '''
-        Custom raw_input() replacement. Get's current line from console buffer.
-
-        @param prompt: Prompt to print. Here for compatability as replacement.
-        @type prompt: string
-
-        @return: The current command line text.
-        @rtype: string
-        '''
-        return self._line_to_execute
-
-    def _execute(self):
-        '''
-        Executes the current line provided by the shell object.
-        '''
-        orig_stdout = sys.stdout
-        sys.stdout = IPython.Shell.Term.cout
                 
-        try:
-            line = self._IP.raw_input(None, self._iter_more)
-            if self._IP.autoindent:
-                self._IP.readline_startup_hook(None)
-
-        except KeyboardInterrupt:
-            self._IP.write('\nKeyboardInterrupt\n')
-            self._IP.resetbuffer()
-            # keep cache in sync with the prompt counter:
-            self._IP.outputcache.prompt_count -= 1
-
-            if self._IP.autoindent:
-                self._IP.indent_current_nsp = 0
-            self._iter_more = 0
-        except:
-            self._IP.showtraceback()
-        else:
-            self._iter_more = self._IP.push(line)
-            if (self._IP.SyntaxTB.last_syntax_error and
-                    self._IP.rc.autoedit_syntax):
-                self._IP.edit_syntax_error()
-        if self._iter_more:
-            self._prompt = str(self._IP.outputcache.prompt2).strip()
-            if self._IP.autoindent:
-                self._IP.readline_startup_hook(self._IP.pre_readline)
-        else:
-            self._prompt = str(self._IP.outputcache.prompt1).strip()
-            self._IP.indent_current_nsp = 0 #we set indentation to 0
-        sys.stdout = orig_stdout
-    
-    def _shell(self, ip, cmd):
-        '''
-        Replacement method to allow shell commands without them blocking.
-
-        @param ip: Ipython instance, same as self._IP
-        @type cmd: Ipython instance
-        @param cmd: Shell command to execute.
-        @type cmd: string
-        '''
-        stdin, stdout = os.popen4(cmd)
-        result = stdout.read().decode('cp437').encode(locale.getpreferredencoding())
-        #we use print command because the shell command is called inside IPython instance and thus is
-        #redirected to thread cout
-        #"\x01\x1b[1;36m\x02" <-- add colour to the text...
-        print "\x01\x1b[1;36m\x02"+result
-        stdout.close()
-        stdin.close()
-
 class WxConsoleView(stc.StyledTextCtrl):
     '''
     Specialized styled text control view for console-like workflow.
-    We use here a scintilla frontend thus it can be reused in any GUI taht supports
-    scintilla with less work.
+    We use here a scintilla frontend thus it can be reused in any GUI that 
+    supports scintilla with less work.
 
-    @cvar ANSI_COLORS_BLACK: Mapping of terminal colors to X11 names.(with Black background)
+    @cvar ANSI_COLORS_BLACK: Mapping of terminal colors to X11 names.
+                    (with Black background)
     @type ANSI_COLORS_BLACK: dictionary
 
-    @cvar ANSI_COLORS_WHITE: Mapping of terminal colors to X11 names.(with White background)
+    @cvar ANSI_COLORS_WHITE: Mapping of terminal colors to X11 names.
+                    (with White background)
     @type ANSI_COLORS_WHITE: dictionary
 
     @ivar color_pat: Regex of terminal color pattern
     @type color_pat: _sre.SRE_Pattern
     '''
-    ANSI_STYLES_BLACK ={'0;30': [0,'WHITE'],             '0;31': [1,'RED'],
-                        '0;32': [2,'GREEN'],             '0;33': [3,'BROWN'],
-                        '0;34': [4,'BLUE'],              '0;35': [5,'PURPLE'],
-                        '0;36': [6,'CYAN'],              '0;37': [7,'LIGHT GREY'],
-                        '1;30': [8,'DARK GREY'],         '1;31': [9,'RED'],
-                        '1;32': [10,'SEA GREEN'],        '1;33': [11,'YELLOW'],
-                        '1;34': [12,'LIGHT BLUE'],       '1;35': [13,'MEDIUM VIOLET RED'],
-                        '1;36': [14,'LIGHT STEEL BLUE'], '1;37': [15,'YELLOW']}
-
-    ANSI_STYLES_WHITE ={'0;30': [0,'BLACK'],             '0;31': [1,'RED'],
-                        '0;32': [2,'GREEN'],             '0;33': [3,'BROWN'],
-                        '0;34': [4,'BLUE'],              '0;35': [5,'PURPLE'],
-                        '0;36': [6,'CYAN'],              '0;37': [7,'LIGHT GREY'],
-                        '1;30': [8,'DARK GREY'],         '1;31': [9,'RED'],
-                        '1;32': [10,'SEA GREEN'],        '1;33': [11,'YELLOW'],
-                        '1;34': [12,'LIGHT BLUE'],       '1;35': [13,'MEDIUM VIOLET RED'],
-                        '1;36': [14,'LIGHT STEEL BLUE'], '1;37': [15,'YELLOW']}
-
-    def __init__(self,parent,prompt,intro="",background_color="BLACK",pos=wx.DefaultPosition, ID = -1, size=wx.DefaultSize,
-                 style=0):
+    ANSI_STYLES_BLACK={'0;30': [0,'WHITE'],            '0;31': [1,'RED'],
+                       '0;32': [2,'GREEN'],            '0;33': [3,'BROWN'],
+                       '0;34': [4,'BLUE'],             '0;35': [5,'PURPLE'],
+                       '0;36': [6,'CYAN'],             '0;37': [7,'LIGHT GREY'],
+                       '1;30': [8,'DARK GREY'],        '1;31': [9,'RED'],
+                       '1;32': [10,'SEA GREEN'],       '1;33': [11,'YELLOW'],
+                       '1;34': [12,'LIGHT BLUE'],      '1;35': 
+                                                    [13,'MEDIUM VIOLET RED'],
+                       '1;36': [14,'LIGHT STEEL BLUE'],'1;37': [15,'YELLOW']}
+
+    ANSI_STYLES_WHITE={'0;30': [0,'BLACK'],            '0;31': [1,'RED'],
+                       '0;32': [2,'GREEN'],            '0;33': [3,'BROWN'],
+                       '0;34': [4,'BLUE'],             '0;35': [5,'PURPLE'],
+                       '0;36': [6,'CYAN'],             '0;37': [7,'LIGHT GREY'],
+                       '1;30': [8,'DARK GREY'],        '1;31': [9,'RED'],
+                       '1;32': [10,'SEA GREEN'],       '1;33': [11,'YELLOW'],
+                       '1;34': [12,'LIGHT BLUE'],      '1;35':
+                                                    [13,'MEDIUM VIOLET RED'],
+                       '1;36': [14,'LIGHT STEEL BLUE'],'1;37': [15,'YELLOW']}
+
+    def __init__(self,parent,prompt,intro="",background_color="BLACK",
+                 pos=wx.DefaultPosition, ID = -1, size=wx.DefaultSize,
+                 style=0, autocomplete_mode = 'IPYTHON'):
         '''
         Initialize console view.
 
@@ -464,15 +119,61 b' class WxConsoleView(stc.StyledTextCtrl):'
         @param background_color: Can be BLACK or WHITE
         @type background_color: string
         @param other: init param of styledTextControl (can be used as-is)
+        @param autocomplete_mode: Can be 'IPYTHON' or 'STC'
+            'IPYTHON' show autocompletion the ipython way
+            'STC" show it scintilla text control way
         '''
         stc.StyledTextCtrl.__init__(self, parent, ID, pos, size, style)
 
-        ####### Scintilla configuration ##################################################
+        ####### Scintilla configuration ###################################
         
-        # Ctrl + B or Ctrl + N can be used to zoomin/zoomout the text inside the widget
+        # Ctrl + B or Ctrl + N can be used to zoomin/zoomout the text inside 
+        # the widget
         self.CmdKeyAssign(ord('B'), stc.STC_SCMOD_CTRL, stc.STC_CMD_ZOOMIN)
         self.CmdKeyAssign(ord('N'), stc.STC_SCMOD_CTRL, stc.STC_CMD_ZOOMOUT)
 
+        #We draw a line at position 80
+        self.SetEdgeMode(stc.STC_EDGE_LINE)
+        self.SetEdgeColumn(80)
+        self.SetEdgeColour(wx.LIGHT_GREY)
+
+        #self.SetViewWhiteSpace(True)
+        #self.SetViewEOL(True)
+        self.SetEOLMode(stc.STC_EOL_CRLF)
+        #self.SetWrapMode(stc.STC_WRAP_CHAR)
+        #self.SetWrapMode(stc.STC_WRAP_WORD)
+        self.SetBufferedDraw(True)
+        #self.SetUseAntiAliasing(True)
+        self.SetLayoutCache(stc.STC_CACHE_PAGE)
+        self.SetUndoCollection(False)
+	self.SetUseTabs(True)
+	self.SetIndent(4)
+	self.SetTabWidth(4)
+
+        self.EnsureCaretVisible()
+        
+        self.SetMargins(3,3) #text is moved away from border with 3px
+        # Suppressing Scintilla margins
+        self.SetMarginWidth(0,0)
+        self.SetMarginWidth(1,0)
+        self.SetMarginWidth(2,0)
+
+        self.background_color = background_color
+        self.buildStyles()
+        
+        self.indent = 0
+        self.prompt_count = 0
+        self.color_pat = re.compile('\x01?\x1b\[(.*?)m\x02?')
+        
+        self.write(intro)
+        self.setPrompt(prompt)
+        self.showPrompt()
+
+        self.autocomplete_mode = autocomplete_mode
+        
+        self.Bind(wx.EVT_KEY_DOWN, self._onKeypress)
+        
+    def buildStyles(self):
         #we define platform specific fonts
         if wx.Platform == '__WXMSW__':
                 faces = { 'times': 'Times New Roman',
@@ -499,61 +200,64 b' class WxConsoleView(stc.StyledTextCtrl):'
                       'size2': 8,
                      }
 
-        #We draw a line at position 80
-        self.SetEdgeMode(stc.STC_EDGE_LINE)
-        self.SetEdgeColumn(80)
-        self.SetEdgeColour(wx.LIGHT_GREY)
-
-        #self.SetViewWhiteSpace(True)
-        #self.SetViewEOL(True)
-        self.SetEOLMode(stc.STC_EOL_CRLF)
-        #self.SetWrapMode(stc.STC_WRAP_CHAR)
-        #self.SetWrapMode(stc.STC_WRAP_WORD)
-        self.SetBufferedDraw(True)
-        #self.SetUseAntiAliasing(True)
-        self.SetLayoutCache(stc.STC_CACHE_PAGE)
-
-        self.EnsureCaretVisible()
-        
-        self.SetMargins(3,3) #text is moved away from border with 3px
-        # Suppressing Scintilla margins
-        self.SetMarginWidth(0,0)
-        self.SetMarginWidth(1,0)
-        self.SetMarginWidth(2,0)
-
         # make some styles
-        if background_color != "BLACK":
+        if self.background_color != "BLACK":
             self.background_color = "WHITE"
             self.SetCaretForeground("BLACK")
             self.ANSI_STYLES = self.ANSI_STYLES_WHITE
         else:
-            self.background_color = background_color
             self.SetCaretForeground("WHITE")
             self.ANSI_STYLES = self.ANSI_STYLES_BLACK
 
-        self.StyleSetSpec(stc.STC_STYLE_DEFAULT, "fore:%s,back:%s,size:%d,face:%s" % (self.ANSI_STYLES['0;30'][1],
-                                                                                      self.background_color,
-                                                                                      faces['size'], faces['mono']))
+        self.StyleSetSpec(stc.STC_STYLE_DEFAULT, 
+                          "fore:%s,back:%s,size:%d,face:%s" 
+                                    % (self.ANSI_STYLES['0;30'][1],
+                          self.background_color,
+                          faces['size'], faces['mono']))
         self.StyleClearAll()
-        self.StyleSetSpec(stc.STC_STYLE_BRACELIGHT,  "fore:#FF0000,back:#0000FF,bold")
-        self.StyleSetSpec(stc.STC_STYLE_BRACEBAD,    "fore:#000000,back:#FF0000,bold")
-    
+        self.StyleSetSpec(stc.STC_STYLE_BRACELIGHT,  
+                          "fore:#FF0000,back:#0000FF,bold")
+        self.StyleSetSpec(stc.STC_STYLE_BRACEBAD,
+                          "fore:#000000,back:#FF0000,bold")
+
         for style in self.ANSI_STYLES.values():
             self.StyleSetSpec(style[0], "bold,fore:%s" % style[1])
         
         #######################################################################
         
-        self.indent = 0
-        self.prompt_count = 0
-        self.color_pat = re.compile('\x01?\x1b\[(.*?)m\x02?')
+    def setBackgroundColor(self,color):
+        self.background_color = color
+        self.buildStyles()
+
+    def getBackgroundColor(self,color):
+        return self.background_color
         
-        self.write(intro)
-        self.setPrompt(prompt)
-        self.showPrompt()
+    def asyncWrite(self, text):
+        '''
+        Write given text to buffer in an asynchroneous way.
+        It is used from another thread to be able to acces the GUI.
+        @param text: Text to append
+        @type text: string
+        '''
+        try:
+                #print >>sys.__stdout__,'entering'
+                wx.MutexGuiEnter()
+                #print >>sys.__stdout__,'locking the GUI'
+                
+                #be sure not to be interrutpted before the MutexGuiLeave!
+                self.write(text)
+                
+                #print >>sys.__stdout__,'done'
+                
+        except KeyboardInterrupt:
+                #print >>sys.__stdout__,'got keyboard interrupt'
+                wx.MutexGuiLeave()
+                #print >>sys.__stdout__,'interrupt unlock the GUI'
+                raise KeyboardInterrupt
+        wx.MutexGuiLeave()
+        #print >>sys.__stdout__,'normal unlock the GUI'
         
-        self.Bind(wx.EVT_KEY_DOWN, self._onKeypress, self)
-        #self.Bind(stc.EVT_STC_UPDATEUI, self.OnUpdateUI)
-
+                
     def write(self, text):
         '''
         Write given text to buffer.
@@ -641,18 +345,6 b' class WxConsoleView(stc.StyledTextCtrl):'
         return self.GetTextRange(self.getCurrentPromptStart(),
                                  self.getCurrentLineEnd())
 
-    def showReturned(self, text):
-        '''
-        Show returned text from last command and print new prompt.
-
-        @param text: Text to show.
-        @type text: string
-        '''
-        self.write('\n'+text)
-        if text:
-            self.write('\n')
-        self.showPrompt()
-
     def moveCursorOnNewValidKey(self):
         #If cursor is at wrong position put it at last line...
         if self.GetCurrentPos() < self.getCurrentPromptStart():
@@ -679,33 +371,53 b' class WxConsoleView(stc.StyledTextCtrl):'
     def writeHistory(self,history):
         self.removeFromTo(self.getCurrentPromptStart(),self.getCurrentLineEnd())
         self.changeLine(history)
+
+    def setCompletionMethod(self, completion):
+        if completion in ['IPYTHON','STC']:
+            self.autocomplete_mode = completion
+        else:
+            raise AttributeError
+
+    def getCompletionMethod(self, completion):
+        return self.autocomplete_mode
         
     def writeCompletion(self, possibilities):
-        max_len = len(max(possibilities,key=len))
-        max_symbol =' '*max_len
-        
-        #now we check how much symbol we can put on a line...
-        cursor_pos = self.getCursorPos()
-        test_buffer = max_symbol + ' '*4
-        current_lines = self.GetLineCount()
-        
-        allowed_symbols = 80/len(test_buffer)
-        if allowed_symbols == 0:
-                allowed_symbols = 1
+        if self.autocomplete_mode == 'IPYTHON':
+            max_len = len(max(possibilities,key=len))
+            max_symbol =' '*max_len
+            
+            #now we check how much symbol we can put on a line...
+            cursor_pos = self.getCursorPos()
+            test_buffer = max_symbol + ' '*4
+            current_lines = self.GetLineCount()
+            
+            allowed_symbols = 80/len(test_buffer)
+            if allowed_symbols == 0:
+                    allowed_symbols = 1
+            
+            pos = 1
+            buf = ''
+            for symbol in possibilities:
+                #buf += symbol+'\n'#*spaces)
+                if pos<allowed_symbols:
+                    spaces = max_len - len(symbol) + 4
+                    buf += symbol+' '*spaces
+                    pos += 1
+                else:
+                    buf+=symbol+'\n'
+                    pos = 1
+            self.write(buf)
+        else:
+            possibilities.sort()  # Python sorts are case sensitive
+            self.AutoCompSetIgnoreCase(False)
+            self.AutoCompSetAutoHide(False)
+            #let compute the length ot last word
+            splitter = [' ','(','[','{']
+            last_word = self.getCurrentLine()
+            for breaker in splitter:
+                last_word = last_word.split(breaker)[-1]
+            self.AutoCompShow(len(last_word), " ".join(possibilities))
         
-        pos = 1
-        buf = ''
-        for symbol in possibilities:
-            #buf += symbol+'\n'#*spaces)
-            if pos<allowed_symbols:
-                spaces = max_len - len(symbol) + 4
-                buf += symbol+' '*spaces
-                pos += 1
-            else:
-                buf+=symbol+'\n'
-                pos = 1
-        self.write(buf)
-                             
     def _onKeypress(self, event, skip=True):
         '''
         Key press callback used for correcting behavior for console-like
@@ -720,42 +432,45 b' class WxConsoleView(stc.StyledTextCtrl):'
         @return: Return True if event as been catched.
         @rtype: boolean
         '''
-	
-        if event.GetKeyCode() == wx.WXK_HOME:
-            if event.Modifiers == wx.MOD_NONE:
-                self.moveCursorOnNewValidKey()
-                self.moveCursor(self.getCurrentPromptStart())
-                return True
-            elif event.Modifiers == wx.MOD_SHIFT:
-                self.moveCursorOnNewValidKey()
-                self.selectFromTo(self.getCurrentPromptStart(),self.getCursorPos())
-                return True
-            else:
-                return False
 
-        elif event.GetKeyCode() == wx.WXK_LEFT:
-            if event.Modifiers == wx.MOD_NONE:
-                self.moveCursorOnNewValidKey()
-                
-                self.moveCursor(self.getCursorPos()-1)
-                if self.getCursorPos() < self.getCurrentPromptStart():
+        if not self.AutoCompActive():
+            if event.GetKeyCode() == wx.WXK_HOME:
+                if event.Modifiers == wx.MOD_NONE:
+                    self.moveCursorOnNewValidKey()
                     self.moveCursor(self.getCurrentPromptStart())
-                return True
-
-        elif event.GetKeyCode() == wx.WXK_BACK:
-            self.moveCursorOnNewValidKey()
-	    if self.getCursorPos() > self.getCurrentPromptStart():
-                self.removeFromTo(self.getCursorPos()-1,self.getCursorPos())
-	    return True
-        
-        if skip:
-            if event.GetKeyCode() not in [wx.WXK_PAGEUP,wx.WXK_PAGEDOWN] and event.Modifiers == wx.MOD_NONE:
+                    return True
+                elif event.Modifiers == wx.MOD_SHIFT:
+                    self.moveCursorOnNewValidKey()
+                    self.selectFromTo(self.getCurrentPromptStart(),self.getCursorPos())
+                    return True
+                else:
+                    return False
+
+            elif event.GetKeyCode() == wx.WXK_LEFT:
+                if event.Modifiers == wx.MOD_NONE:
+                    self.moveCursorOnNewValidKey()
+                    
+                    self.moveCursor(self.getCursorPos()-1)
+                    if self.getCursorPos() < self.getCurrentPromptStart():
+                        self.moveCursor(self.getCurrentPromptStart())
+                    return True
+
+            elif event.GetKeyCode() == wx.WXK_BACK:
                 self.moveCursorOnNewValidKey()
-                
+                if self.getCursorPos() > self.getCurrentPromptStart():
+                    event.Skip()
+                return True
+            
+            if skip:
+                if event.GetKeyCode() not in [wx.WXK_PAGEUP,wx.WXK_PAGEDOWN] and event.Modifiers == wx.MOD_NONE:
+                    self.moveCursorOnNewValidKey()
+                    
+                event.Skip()
+                return True
+            return False
+        else:
             event.Skip()
-            return True
-        return False
-
+            
     def OnUpdateUI(self, evt):
         # check for matching braces
         braceAtCaret = -1
@@ -791,49 +506,90 b' class WxConsoleView(stc.StyledTextCtrl):'
             #print pt
             #self.Refresh(False)
         
-class WxIPythonViewPanel(wx.Panel):
+class IPShellWidget(wx.Panel):
     '''
     This is wx.Panel that embbed the IPython Thread and the wx.StyledTextControl
-    If you want to port this to any other GUI toolkit, just replace the WxConsoleView
-    by YOURGUIConsoleView and make YOURGUIIPythonView derivate from whatever container you want.
-    I've choosed to derivate from a wx.Panel because it seems to be ore usefull
-    Any idea to make it more 'genric' welcomed.
+    If you want to port this to any other GUI toolkit, just replace the 
+    WxConsoleView by YOURGUIConsoleView and make YOURGUIIPythonView derivate 
+    from whatever container you want. I've choosed to derivate from a wx.Panel 
+    because it seems to be more useful
+    Any idea to make it more 'generic' welcomed.
     '''
-    def __init__(self,parent,exit_handler=None,intro=None,background_color="BLACK"):
+
+    def __init__(self, parent, intro=None,
+                 background_color="BLACK", add_button_handler=None, 
+                 wx_ip_shell=None, user_ns={},user_global_ns=None,
+                 ):
         '''
         Initialize.
         Instanciate an IPython thread.
         Instanciate a WxConsoleView.
         Redirect I/O to console.
         '''
-        wx.Panel.__init__(self,parent,-1)
+        wx.Panel.__init__(self,parent,wx.ID_ANY)
 
-        ### IPython thread instanciation ###
+        self.parent = parent
+        ### IPython non blocking shell instanciation ###
         self.cout = StringIO()
-        self.IP = IterableIPShell(cout=self.cout,cerr=self.cout,
-                             exit_handler = exit_handler,
-                             time_loop = 0.1)
-        self.IP.start()
-        
+        self.add_button_handler = add_button_handler
+
+        if wx_ip_shell is not None:
+            self.IP = wx_ip_shell
+        else:
+            self.IP = WxNonBlockingIPShell(self,
+                                    cout = self.cout, cerr = self.cout,
+                                    ask_exit_handler = self.askExitCallback)
+
         ### IPython wx console view instanciation ###
         #If user didn't defined an intro text, we create one for him
-        #If you really wnat an empty intrp just call wxIPythonViewPanel with intro=''
-        if intro == None:
+        #If you really wnat an empty intro just call wxIPythonViewPanel 
+        #with intro=''
+        if intro is None:
             welcome_text = "Welcome to WxIPython Shell.\n\n"
             welcome_text+= self.IP.getBanner()
             welcome_text+= "!command  -> Execute command in shell\n"
             welcome_text+= "TAB       -> Autocompletion\n"
+        else:
+            welcome_text = intro
 
         self.text_ctrl = WxConsoleView(self,
                                        self.IP.getPrompt(),
                                        intro=welcome_text,
                                        background_color=background_color)
-        
-        self.text_ctrl.Bind(wx.EVT_KEY_DOWN, self.keyPress, self.text_ctrl)
 
+        self.cout.write = self.text_ctrl.asyncWrite
+
+        option_text = wx.StaticText(self, -1, "Options:")
+        self.completion_option = wx.CheckBox(self, -1, "Scintilla Completion")
+        #self.completion_option.SetValue(False)
+        self.background_option = wx.CheckBox(self, -1, "White Background")
+        #self.background_option.SetValue(False)
+        
+        self.options={'completion':{'value':'IPYTHON',
+                                    'checkbox':self.completion_option,'STC':True,'IPYTHON':False,
+                                    'setfunc':self.text_ctrl.setCompletionMethod},
+                      'background_color':{'value':'BLACK',
+                                          'checkbox':self.background_option,'WHITE':True,'BLACK':False,
+                                          'setfunc':self.text_ctrl.setBackgroundColor},
+                     }
+        self.reloadOptions(self.options)
+        
+        self.text_ctrl.Bind(wx.EVT_KEY_DOWN, self.keyPress)
+        self.completion_option.Bind(wx.EVT_CHECKBOX, self.evtCheckOptionCompletion)
+        self.background_option.Bind(wx.EVT_CHECKBOX, self.evtCheckOptionBackgroundColor)
+            
         ### making the layout of the panel ###
         sizer = wx.BoxSizer(wx.VERTICAL)
         sizer.Add(self.text_ctrl, 1, wx.EXPAND)
+        option_sizer = wx.BoxSizer(wx.HORIZONTAL)
+        sizer.Add(option_sizer, 0)
+        option_sizer.AddMany([(10, 20),
+                              (option_text, 0, wx.ALIGN_CENTER_VERTICAL),
+                              (5, 5),
+                              (self.completion_option, 0, wx.ALIGN_CENTER_VERTICAL),
+                              (8, 8),
+                              (self.background_option, 0, wx.ALIGN_CENTER_VERTICAL)
+                              ])
         self.SetAutoLayout(True)
         sizer.Fit(self)
         sizer.SetSizeHints(self)
@@ -841,158 +597,151 b' class WxIPythonViewPanel(wx.Panel):'
         #and we focus on the widget :)
         self.SetFocus()
 
-        ### below are the thread communication variable ###
-        # the IPython thread is managed via unidirectional communication.
-        # It's a thread slave that can't interact by itself with the GUI.
-        # When the GUI event loop is done runStateMachine() is called and the thread sate is then
-        # managed.
-        
-        #Initialize the state machine #kept for information
-        #self.states = ['IDLE',
-        #               'DO_EXECUTE_LINE',
-        #               'WAIT_END_OF_EXECUTION',
-        #               'SHOW_DOC',
-        #               'SHOW_PROMPT']
-        
-        self.cur_state = 'IDLE'
-	self.pager_state = 'DONE'
-        #wx.CallAfter(self.runStateMachine)
+        #widget state management (for key handling different cases)
+        self.setCurrentState('IDLE')
+        self.pager_state = 'DONE'
+        self.raw_input_current_line = 0
+
+    def askExitCallback(self, event):
+        self.askExitHandler(event)
+        
+    #---------------------- IPython Thread Management ------------------------
+    def stateDoExecuteLine(self):
+        lines=self.text_ctrl.getCurrentLine()
+        self.text_ctrl.write('\n')
+        lines_to_execute = lines.replace('\t',' '*4)
+        lines_to_execute = lines_to_execute.replace('\r','')
+        self.IP.doExecute(lines_to_execute.encode('cp1252'))
+        self.updateHistoryTracker(lines)
+        self.setCurrentState('WAIT_END_OF_EXECUTION')
+        
+    def evtStateExecuteDone(self,evt):
+        self.doc = self.IP.getDocText()
+        self.help = self.IP.getHelpText()
+        if self.doc:
+            self.pager_lines = self.doc[7:].split('\n')
+            self.pager_state = 'INIT'
+            self.setCurrentState('SHOW_DOC')
+            self.pager(self.doc)
+        elif self.help:
+            self.pager_lines = self.help.split('\n')
+            self.pager_state = 'INIT'
+            self.setCurrentState('SHOW_DOC')
+            self.pager(self.help)                
+        else:
+            self.stateShowPrompt()
+
+    def stateShowPrompt(self):
+        self.setCurrentState('SHOW_PROMPT')
+        self.text_ctrl.setPrompt(self.IP.getPrompt())
+        self.text_ctrl.setIndentation(self.IP.getIndentation())
+        self.text_ctrl.setPromptCount(self.IP.getPromptCount())
+        self.text_ctrl.showPrompt()
+        self.IP.initHistoryIndex()
+        self.setCurrentState('IDLE')
+
+    def setCurrentState(self, state):
+        self.cur_state = state
+        self.updateStatusTracker(self.cur_state)
 
-        # This creates a new Event class and a EVT binder function
-        (self.AskExitEvent, EVT_ASK_EXIT) = wx.lib.newevent.NewEvent()
+    def pager(self,text):
 
-        self.Bind(wx.EVT_IDLE, self.runStateMachine)
-        self.Bind(EVT_ASK_EXIT, exit_handler)
-        
-    def __del__(self):
-        self.IP.shutdown()
-        self.IP.join()
-        WxConsoleView.__del__()
-        
-    #---------------------------- IPython Thread Management ---------------------------------------
-    def runStateMachine(self,event):
-        #print >>self.sys_stdout,"state:",self.cur_state
-        self.updateStatusTracker(self.cur_state)
-        
-        if self.cur_state == 'DO_EXECUTE_LINE':
-            #print >>self.sys_stdout,"command:",self.getCurrentLine()
-            self.IP.doExecute(self.text_ctrl.getCurrentLine().replace('\t',' '*4))
-            self.updateHistoryTracker(self.text_ctrl.getCurrentLine())
-            self.cur_state = 'WAIT_END_OF_EXECUTION'
-        
-        if self.cur_state == 'WAIT_END_OF_EXECUTION':
-            if self.IP.isExecuteDone():
-                self.doc = self.IP.getDocText()
-                if self.IP.getAskExit():
-                    evt = self.AskExitEvent()
-                    wx.PostEvent(self, evt)
-                    self.IP.clearAskExit()
-                if self.doc:
-                    self.pager_state = 'INIT'
-		    self.cur_state = 'SHOW_DOC'
+        if self.pager_state == 'INIT':
+                #print >>sys.__stdout__,"PAGER state:",self.pager_state
+                self.pager_nb_lines = len(self.pager_lines)
+                self.pager_index = 0
+                self.pager_do_remove = False
+                self.text_ctrl.write('\n')
+                self.pager_state = 'PROCESS_LINES'
+
+        if self.pager_state == 'PROCESS_LINES':
+                #print >>sys.__stdout__,"PAGER state:",self.pager_state
+                if self.pager_do_remove == True:
+                        self.text_ctrl.removeCurrentLine()
+                        self.pager_do_remove = False
+
+                if self.pager_nb_lines > 10:
+                        #print >>sys.__stdout__,"PAGER processing 10 lines"
+                        if self.pager_index > 0:
+                                self.text_ctrl.write(">\x01\x1b[1;36m\x02"+self.pager_lines[self.pager_index]+'\n')
+                        else:
+                                self.text_ctrl.write("\x01\x1b[1;36m\x02 "+self.pager_lines[self.pager_index]+'\n')
+                        
+                        for line in self.pager_lines[self.pager_index+1:self.pager_index+9]:
+                                self.text_ctrl.write("\x01\x1b[1;36m\x02 "+line+'\n')
+                        self.pager_index += 10
+                        self.pager_nb_lines -= 10
+                        self.text_ctrl.write("--- Push Enter to continue or 'Q' to quit---")
+                        self.pager_do_remove = True
+                        self.pager_state = 'WAITING'
+                        return
                 else:
-                    self.cur_state = 'SHOW_PROMPT'
-                
-        if self.cur_state == 'SHOW_PROMPT':
-            self.text_ctrl.setPrompt(self.IP.getPrompt())
-            self.text_ctrl.setIndentation(self.IP.getIndentation())
-            self.text_ctrl.setPromptCount(self.IP.getPromptCount())
-            rv = self.cout.getvalue()
-            if rv: rv = rv.strip('\n')
-            self.text_ctrl.showReturned(rv)
-            self.cout.truncate(0)
-	    self.IP.initHistoryIndex()
-            self.cur_state = 'IDLE'
-            
-        if self.cur_state == 'SHOW_DOC':
-            self.pager(self.doc)
-            if self.pager_state == 'DONE':
-                self.cur_state = 'SHOW_PROMPT'
-                
-        event.Skip()
-
-    #---------------------------- IPython pager ---------------------------------------
-    def pager(self,text):#,start=0,screen_lines=0,pager_cmd = None):
-        if self.pager_state == 'WAITING':
-		#print >>self.sys_stdout,"PAGER waiting"
-        	return
-	
-	if self.pager_state == 'INIT':
-		#print >>self.sys_stdout,"PAGER state:",self.pager_state
-        	self.pager_lines = text[7:].split('\n')
-		self.pager_nb_lines = len(self.pager_lines)
-		self.pager_index = 0
-		self.pager_do_remove = False
-		self.text_ctrl.write('\n')
-		self.pager_state = 'PROCESS_LINES'
-		
-	if self.pager_state == 'PROCESS_LINES':
-        	#print >>self.sys_stdout,"PAGER state:",self.pager_state
-        	if self.pager_do_remove == True:
-			self.text_ctrl.removeCurrentLine()
-			self.pager_do_remove = False
-	
-		if self.pager_nb_lines > 10:
-	                #print >>self.sys_stdout,"PAGER processing 10 lines"
-			if self.pager_index > 0:
-				self.text_ctrl.write(">\x01\x1b[1;36m\x02"+self.pager_lines[self.pager_index]+'\n')
-			else:
-				self.text_ctrl.write("\x01\x1b[1;36m\x02 "+self.pager_lines[self.pager_index]+'\n')
-			
-			for line in self.pager_lines[self.pager_index+1:self.pager_index+9]:
-				self.text_ctrl.write("\x01\x1b[1;36m\x02 "+line+'\n')
-			self.pager_index += 10
-			self.pager_nb_lines -= 10
-			self.text_ctrl.write("--- Push Enter to continue or 'Q' to quit---")
-			self.pager_do_remove = True
-			self.pager_state = 'WAITING'
-			return
-        	else:
-	                #print >>self.sys_stdout,"PAGER processing last lines"
-			if self.pager_nb_lines > 0:
-				if self.pager_index > 0:
-					self.text_ctrl.write(">\x01\x1b[1;36m\x02"+self.pager_lines[self.pager_index]+'\n')
-				else:
-					self.text_ctrl.write("\x01\x1b[1;36m\x02 "+self.pager_lines[self.pager_index]+'\n')
-				
-				self.pager_index += 1
+                        #print >>sys.__stdout__,"PAGER processing last lines"
+                        if self.pager_nb_lines > 0:
+                                if self.pager_index > 0:
+                                        self.text_ctrl.write(">\x01\x1b[1;36m\x02"+self.pager_lines[self.pager_index]+'\n')
+                                else:
+                                        self.text_ctrl.write("\x01\x1b[1;36m\x02 "+self.pager_lines[self.pager_index]+'\n')
+                                
+                                self.pager_index += 1
                                 self.pager_nb_lines -= 1
-	              	if self.pager_nb_lines > 0:
-        	        	for line in self.pager_lines[self.pager_index:]:
-					self.text_ctrl.write("\x01\x1b[1;36m\x02 "+line+'\n')
-                			self.pager_nb_lines = 0
-			self.pager_state = 'DONE'          
+                        if self.pager_nb_lines > 0:
+                                for line in self.pager_lines[self.pager_index:]:
+                                        self.text_ctrl.write("\x01\x1b[1;36m\x02 "+line+'\n')
+                                        self.pager_nb_lines = 0
+                        self.pager_state = 'DONE'
+                        self.stateShowPrompt()
                 
-    #---------------------------- Key Handler --------------------------------------------
+    #------------------------ Key Handler ------------------------------------
     def keyPress(self, event):
         '''
         Key press callback with plenty of shell goodness, like history,
         autocompletions, etc.
         '''
-	
         if event.GetKeyCode() == ord('C'):
-            if event.Modifiers == wx.MOD_CONTROL:
+            if event.Modifiers == wx.MOD_CONTROL or event.Modifiers == wx.MOD_ALT:
                 if self.cur_state == 'WAIT_END_OF_EXECUTION':
                     #we raise an exception inside the IPython thread container
-                    self.IP.raise_exc(KeyboardInterrupt)
+                    self.IP.ce.raise_exc(KeyboardInterrupt)
                     return
                 
+        #let this before 'wx.WXK_RETURN' because we have to put 'IDLE'
+        #mode if AutoComp has been set as inactive
+        if self.cur_state == 'COMPLETING':
+            if not self.text_ctrl.AutoCompActive():
+                self.cur_state = 'IDLE'
+            else:
+                event.Skip()
+
         if event.KeyCode == wx.WXK_RETURN:
             if self.cur_state == 'IDLE':
                 #we change the state ot the state machine
-                self.cur_state = 'DO_EXECUTE_LINE'
+                self.setCurrentState('DO_EXECUTE_LINE')
+                self.stateDoExecuteLine()
                 return
+
             if self.pager_state == 'WAITING':
                 self.pager_state = 'PROCESS_LINES'
+                self.pager(self.doc)
                 return
             
+            if self.cur_state == 'WAITING_USER_INPUT':
+                line=self.text_ctrl.getCurrentLine()
+                self.text_ctrl.write('\n')
+                self.setCurrentState('WAIT_END_OF_EXECUTION')
+                return
+          
         if event.GetKeyCode() in [ord('q'),ord('Q')]:
             if self.pager_state == 'WAITING':
                 self.pager_state = 'DONE'
+                self.text_ctrl.write('\n')
+                self.stateShowPrompt()
                 return
+
+        if self.cur_state == 'WAITING_USER_INPUT':
+            event.Skip()   
             
-        #scroll_position = self.text_ctrl.GetScrollPos(wx.VERTICAL)
-	if self.cur_state == 'IDLE':
+        if self.cur_state == 'IDLE':
             if event.KeyCode == wx.WXK_UP:
                 history = self.IP.historyBack()
                 self.text_ctrl.writeHistory(history)
@@ -1008,19 +757,68 b' class WxIPythonViewPanel(wx.Panel):'
                     return
                 completed, possibilities = self.IP.complete(self.text_ctrl.getCurrentLine())
                 if len(possibilities) > 1:
-                    cur_slice = self.text_ctrl.getCurrentLine()
-                    self.text_ctrl.write('\n')
-                    self.text_ctrl.writeCompletion(possibilities)
-                    self.text_ctrl.write('\n')
-
-                    self.text_ctrl.showPrompt()
-                    self.text_ctrl.write(cur_slice)
-                self.text_ctrl.changeLine(completed or cur_slice)
-                
+                    if self.text_ctrl.autocomplete_mode == 'IPYTHON':    
+                        cur_slice = self.text_ctrl.getCurrentLine()
+                        self.text_ctrl.write('\n')
+                        self.text_ctrl.writeCompletion(possibilities)
+                        self.text_ctrl.write('\n')
+
+                        self.text_ctrl.showPrompt()
+                        self.text_ctrl.write(cur_slice)
+                        self.text_ctrl.changeLine(completed or cur_slice)
+                    else:
+                        self.cur_state = 'COMPLETING'
+                        self.text_ctrl.writeCompletion(possibilities)
+                else:
+                    self.text_ctrl.changeLine(completed or cur_slice)
                 return
             event.Skip()
-	
-    #---------------------------- Hook Section --------------------------------------------
+
+    #------------------------ Option Section ---------------------------------
+    def evtCheckOptionCompletion(self, event):
+        if event.IsChecked():
+            self.options['completion']['value']='STC'
+        else:
+            self.options['completion']['value']='IPYTHON'
+        self.text_ctrl.setCompletionMethod(self.options['completion']['value'])
+        self.updateOptionTracker('completion',
+                                 self.options['completion']['value'])
+        self.text_ctrl.SetFocus()
+
+    def evtCheckOptionBackgroundColor(self, event):
+        if event.IsChecked():
+            self.options['background_color']['value']='WHITE'
+        else:
+            self.options['background_color']['value']='BLACK'
+        self.text_ctrl.setBackgroundColor(self.options['background_color']['value'])
+        self.updateOptionTracker('background_color',
+                                 self.options['background_color']['value'])
+        self.text_ctrl.SetFocus()
+    
+    def getOptions(self):
+        return self.options
+        
+    def reloadOptions(self,options):
+        self.options = options
+        for key in self.options.keys():
+            value = self.options[key]['value']
+            self.options[key]['checkbox'].SetValue(self.options[key][value])
+            self.options[key]['setfunc'](value)
+        
+        
+    #------------------------ Hook Section -----------------------------------
+    def updateOptionTracker(self,name,value):
+        '''
+        Default history tracker (does nothing)
+        '''
+        pass
+    
+    def setOptionTrackerHook(self,func):
+        '''
+        Define a new history tracker
+        '''
+        self.updateOptionTracker = func
+
     def updateHistoryTracker(self,command_line):
         '''
         Default history tracker (does nothing)
@@ -1032,6 +830,7 b' class WxIPythonViewPanel(wx.Panel):'
         Define a new history tracker
         '''
         self.updateHistoryTracker = func
+
     def updateStatusTracker(self,status):
         '''
         Default status tracker (does nothing)
@@ -1043,4 +842,36 b' class WxIPythonViewPanel(wx.Panel):'
         Define a new status tracker
         '''
         self.updateStatusTracker = func
-    
+
+    def askExitHandler(self, event):
+        '''
+        Default exit handler
+        '''
+        self.text_ctrl.write('\nExit callback has not been set.')
+
+    def setAskExitHandler(self, func):
+        '''
+        Define an exit handler
+        '''
+        self.askExitHandler = func
+
+if __name__ == '__main__':
+    # Some simple code to test the shell widget.
+    class MainWindow(wx.Frame):
+        def __init__(self, parent, id, title):
+            wx.Frame.__init__(self, parent, id, title, size=(300,250))
+            self._sizer = wx.BoxSizer(wx.VERTICAL)
+            self.shell = IPShellWidget(self)
+            self._sizer.Add(self.shell, 1, wx.EXPAND)
+            self.SetSizer(self._sizer)
+            self.SetAutoLayout(1)
+            self.Show(True)
+
+    app = wx.PySimpleApp()
+    frame = MainWindow(None, wx.ID_ANY, 'Ipython')
+    frame.SetSize((780, 460))
+    shell = frame.shell
+
+    app.MainLoop()
+
+

IPython/gui/wx/thread_ex.py

@@ -1,45 +1,50 b''
-import threading
-import inspect
-import ctypes
- 
- 
-def _async_raise(tid, exctype):
-    """raises the exception, performs cleanup if needed"""
-    if not inspect.isclass(exctype):
-        raise TypeError("Only types can be raised (not instances)")
-    res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, ctypes.py_object(exctype))
-    if res == 0:
-        raise ValueError("invalid thread id")
-    elif res != 1:
-        # """if it returns a number greater than one, you're in trouble, 
-        # and you should call it again with exc=NULL to revert the effect"""
-        ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, 0)
-        raise SystemError("PyThreadState_SetAsyncExc failed")
- 
- 
-class Thread(threading.Thread):
-    def _get_my_tid(self):
-        """determines this (self's) thread id"""
-        if not self.isAlive():
-            raise threading.ThreadError("the thread is not active")
-        
-        # do we have it cached?
-        if hasattr(self, "_thread_id"):
-            return self._thread_id
-        
-        # no, look for it in the _active dict
-        for tid, tobj in threading._active.items():
-            if tobj is self:
-                self._thread_id = tid
-                return tid
-        
-        raise AssertionError("could not determine the thread's id")
-    
-    def raise_exc(self, exctype):
-        """raises the given exception type in the context of this thread"""
-        _async_raise(self._get_my_tid(), exctype)
-    
-    def kill(self):
-        """raises SystemExit in the context of the given thread, which should 
-        cause the thread to exit silently (unless caught)"""
-        self.raise_exc(SystemExit)
+"""
+Thread subclass that can deal with asynchronously function calls via
+raise_exc.
+"""
+
+import threading
+import inspect
+import ctypes
+ 
+ 
+def _async_raise(tid, exctype):
+    """raises the exception, performs cleanup if needed"""
+    if not inspect.isclass(exctype):
+        raise TypeError("Only types can be raised (not instances)")
+    res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, ctypes.py_object(exctype))
+    if res == 0:
+        raise ValueError("invalid thread id")
+    elif res != 1:
+        # """if it returns a number greater than one, you're in trouble, 
+        # and you should call it again with exc=NULL to revert the effect"""
+        ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, 0)
+        raise SystemError("PyThreadState_SetAsyncExc failed")
+ 
+ 
+class ThreadEx(threading.Thread):
+    def _get_my_tid(self):
+        """determines this (self's) thread id"""
+        if not self.isAlive():
+            raise threading.ThreadError("the thread is not active")
+        
+        # do we have it cached?
+        if hasattr(self, "_thread_id"):
+            return self._thread_id
+        
+        # no, look for it in the _active dict
+        for tid, tobj in threading._active.items():
+            if tobj is self:
+                self._thread_id = tid
+                return tid
+        
+        raise AssertionError("could not determine the thread's id")
+    
+    def raise_exc(self, exctype):
+        """raises the given exception type in the context of this thread"""
+        _async_raise(self._get_my_tid(), exctype)
+    
+    def kill(self):
+        """raises SystemExit in the context of the given thread, which should 
+        cause the thread to exit silently (unless caught)"""
+        self.raise_exc(SystemExit)

IPython/gui/wx/wxIPython.py

@@ -2,11 +2,13 b''
 # -*- coding: iso-8859-15 -*-
 
 import wx.aui
-import wx.py
+
+#used for about dialog
 from wx.lib.wordwrap import wordwrap
 
-from ipython_view import *
-from ipython_history import *
+#used for ipython GUI objects
+from IPython.gui.wx.ipython_view import IPShellWidget
+from IPython.gui.wx.ipython_history import IPythonHistoryPanel
 
 __version__ = 0.8
 __author__  = "Laurent Dufrechou"
@@ -20,7 +22,8 b' __license__ = "BSD"'
 class MyFrame(wx.Frame):
     """Creating one main frame for our 
     application with movables windows"""
-    def __init__(self, parent=None, id=-1, title="WxIPython", pos=wx.DefaultPosition,
+    def __init__(self, parent=None, id=-1, title="WxIPython", 
+                pos=wx.DefaultPosition,
                 size=(800, 600), style=wx.DEFAULT_FRAME_STYLE):
         wx.Frame.__init__(self, parent, id, title, pos, size, style)
         self._mgr = wx.aui.AuiManager()
@@ -30,15 +33,18 b' class MyFrame(wx.Frame):'
         
         #create differents panels and make them persistant 
         self.history_panel    = IPythonHistoryPanel(self)
+
+        self.history_panel.setOptionTrackerHook(self.optionSave)
         
-        self.ipython_panel    = WxIPythonViewPanel(self,self.OnExitDlg,
-                                                   background_color = "BLACK")
-        
-        #self.ipython_panel    = WxIPythonViewPanel(self,self.OnExitDlg,
-        #                                           background_color = "WHITE")
-        
+        self.ipython_panel    = IPShellWidget(self,background_color = "BLACK")
+        #self.ipython_panel    = IPShellWidget(self,background_color = "WHITE")
+
         self.ipython_panel.setHistoryTrackerHook(self.history_panel.write)
         self.ipython_panel.setStatusTrackerHook(self.updateStatus)
+        self.ipython_panel.setAskExitHandler(self.OnExitDlg)
+        self.ipython_panel.setOptionTrackerHook(self.optionSave)
+
+        self.optionLoad()
         
         self.statusbar = self.createStatus()
         self.createMenu()
@@ -48,13 +54,11 b' class MyFrame(wx.Frame):'
         # main panels
         self._mgr.AddPane(self.ipython_panel , wx.CENTER, "IPython Shell")
         self._mgr.AddPane(self.history_panel , wx.RIGHT,  "IPython history")
-        
+                
         # now we specify some panel characteristics
         self._mgr.GetPane(self.ipython_panel).CaptionVisible(True);
         self._mgr.GetPane(self.history_panel).CaptionVisible(True);
         self._mgr.GetPane(self.history_panel).MinSize((200,400));
-                
-        
         
         # tell the manager to "commit" all the changes just made
         self._mgr.Update()
@@ -66,7 +70,7 b' class MyFrame(wx.Frame):'
         self.Bind(wx.EVT_MENU,  self.OnShowHistoryPanel,id=wx.ID_HIGHEST+2)
         self.Bind(wx.EVT_MENU,  self.OnShowAbout, id=wx.ID_HIGHEST+3)
         self.Bind(wx.EVT_MENU,  self.OnShowAllPanel,id=wx.ID_HIGHEST+6)
-
+        
         warn_text = 'Hello from IPython and wxPython.\n'
         warn_text +='Please Note that this work is still EXPERIMENTAL\n'
         warn_text +='It does NOT emulate currently all the IPython functions.\n'
@@ -78,7 +82,41 b' class MyFrame(wx.Frame):'
                                )
         dlg.ShowModal()
         dlg.Destroy()
-     
+
+    def optionSave(self, name, value):
+        opt = open('options.conf','w')
+
+        try:
+            options_ipython_panel = self.ipython_panel.getOptions()
+            options_history_panel = self.history_panel.getOptions()
+
+            for key in options_ipython_panel.keys():
+                opt.write(key + '=' + options_ipython_panel[key]['value']+'\n')
+            for key in options_history_panel.keys():
+                opt.write(key + '=' + options_history_panel[key]['value']+'\n')
+        finally:    
+            opt.close()
+        
+    def optionLoad(self):
+        opt = open('options.conf','r')
+        lines = opt.readlines()
+        opt.close()
+                      
+        options_ipython_panel = self.ipython_panel.getOptions()
+        options_history_panel = self.history_panel.getOptions()
+        
+        for line in lines:
+            key = line.split('=')[0]
+            value = line.split('=')[1].replace('\n','').replace('\r','')
+            if key in options_ipython_panel.keys():
+                options_ipython_panel[key]['value'] = value
+            elif key in options_history_panel.keys():
+                options_history_panel[key]['value'] = value
+            else:
+                print >>sys.__stdout__,"Warning: key ",key,"not found in widget options. Check Options.conf"
+        self.ipython_panel.reloadOptions(options_ipython_panel)
+        self.history_panel.reloadOptions(options_history_panel)
+        
     def createMenu(self):
         """local method used to create one menu bar"""
         
@@ -121,6 +159,7 b' class MyFrame(wx.Frame):'
         states = {'IDLE':'Idle',
                   'DO_EXECUTE_LINE':'Send command',
                   'WAIT_END_OF_EXECUTION':'Running command',
+                  'WAITING_USER_INPUT':'Waiting user input',
                   'SHOW_DOC':'Showing doc',
                   'SHOW_PROMPT':'Showing prompt'}
         self.statusbar.SetStatusText(states[text], 0)

IPython/hooks.py

@@ -56,7 +56,7 b' from pprint import PrettyPrinter'
 __all__ = ['editor', 'fix_error_editor', 'result_display',
            'input_prefilter', 'shutdown_hook', 'late_startup_hook',
            'generate_prompt', 'generate_output_prompt','shell_hook',
-           'show_in_pager']
+           'show_in_pager','pre_prompt_hook', 'pre_runcode_hook']
 
 pformat = PrettyPrinter().pformat
 
@@ -227,11 +227,17 b' def show_in_pager(self,s):'
     # raising TryNext here will use the default paging functionality
     raise ipapi.TryNext
 
-def pre_command_hook(self,cmd):
-    """" Executed before starting to execute a command """
+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 post_command_hook(self,cmd):
-    """ Executed after executing a command """
+def pre_runcode_hook(self):
+    """ Executed before running the (prefiltered) code in IPython """
+    return None
     
 

IPython/ipapi.py

@@ -273,15 +273,27 b' class IPApi:'
             """
             res = []
             lines = script.splitlines()
+
             level = 0
             for l in lines:
-                stripped = l.lstrip()
-                if not l.strip():
+                lstripped = l.lstrip()
+                stripped = l.strip()                
+                if not stripped:
                     continue
-                newlevel = len(l) - len(stripped)
-                if level > 0 and newlevel == 0:
+                newlevel = len(l) - len(lstripped)
+                def is_secondary_block_start(s):
+                    if not s.endswith(':'):
+                        return False
+                    if (s.startswith('elif') or 
+                        s.startswith('else') or 
+                        s.startswith('except') or
+                        s.startswith('finally')):
+                        return True
+                        
+                if level > 0 and newlevel == 0 and not is_secondary_block_start(stripped): 
                     # add empty line
                     res.append('')
+                    
                 res.append(l)
                 level = newlevel
             return '\n'.join(res) + '\n'
@@ -291,7 +303,7 b' class IPApi:'
         else:
             script = '\n'.join(lines)
         clean=cleanup_ipy_script(script)
-
+        # print "_ip.runlines() script:\n",clean #dbg
         self.IP.runlines(clean)
     def to_user_ns(self,vars, interactive = True):
         """Inject a group of variables into the IPython user namespace.
@@ -533,7 +545,7 b' class DebugTools:'
         if name in self.hotnames:
             self.debug_stack( "HotName '%s' caught" % name)
 
-def launch_new_instance(user_ns = None):
+def launch_new_instance(user_ns = None,shellclass = None):
     """ Make and start a new ipython instance.
     
     This can be called even without having an already initialized 
@@ -542,7 +554,7 b' def launch_new_instance(user_ns = None):'
     This is also used as the egg entry point for the 'ipython' script.
     
     """
-    ses = make_session(user_ns)
+    ses = make_session(user_ns,shellclass)
     ses.mainloop()
 
 
@@ -578,7 +590,7 b' def make_user_global_ns(ns = None):'
     return ns
 
 
-def make_session(user_ns = None):
+def make_session(user_ns = None, shellclass = None):
     """Makes, but does not launch an IPython session.
     
     Later on you can call obj.mainloop() on the returned object.
@@ -591,6 +603,6 b' def make_session(user_ns = None):'
     WARNING: This should *not* be run when a session exists already."""
 
     import IPython.Shell
-    return IPython.Shell.start(user_ns)
-
-
+    if shellclass is None:
+        return IPython.Shell.start(user_ns)
+    return shellclass(user_ns = user_ns)

IPython/iplib.py

@@ -6,7 +6,6 b' Requires Python 2.3 or newer.'
 
 This file contains all the classes and helper functions specific to IPython.
 
-$Id: iplib.py 3005 2008-02-01 16:43:34Z vivainio $
 """
 
 #*****************************************************************************
@@ -55,6 +54,8 b' import sys'
 import tempfile
 import traceback
 import types
+import warnings
+warnings.filterwarnings('ignore', r'.*sets module*')
 from sets import Set
 from pprint import pprint, pformat
 
@@ -377,7 +378,10 b' class InteractiveShell(object,Magic):'
         # Get system encoding at startup time.  Certain terminals (like Emacs
         # under Win32 have it set to None, and we need to have a known valid
         # encoding to use in the raw_input() method
-        self.stdin_encoding = sys.stdin.encoding or 'ascii'
+        try:
+            self.stdin_encoding = sys.stdin.encoding or 'ascii'
+        except AttributeError:
+            self.stdin_encoding = 'ascii'
 
         # dict of things NOT to alias (keywords, builtins and some magics)
         no_alias = {}
@@ -698,7 +702,10 b' class InteractiveShell(object,Magic):'
 
         # Do a proper resetting of doctest, including the necessary displayhook
         # monkeypatching
-        doctest_reload()
+        try:
+            doctest_reload()
+        except ImportError:
+            warn("doctest module does not exist.")
         
         # Set user colors (don't do it in the constructor above so that it
         # doesn't crash if colors option is invalid)
@@ -1266,8 +1273,12 b' want to merge them back into the new files.""" % locals()'
         """Reload the input history from disk file."""
 
         if self.has_readline:
-            self.readline.clear_history()
-            self.readline.read_history_file(self.shell.histfile)
+            try:
+                self.readline.clear_history()
+                self.readline.read_history_file(self.shell.histfile)
+            except AttributeError:
+                pass
+            
 
     def history_saving_wrapper(self, func):
         """ Wrap func for readline history saving
@@ -1744,6 +1755,7 b' want to merge them back into the new files.""" % locals()'
         # exit_now is set by a call to %Exit or %Quit
         
         while not self.exit_now:
+            self.hooks.pre_prompt_hook()
             if more:
                 try:
                     prompt = self.hooks.generate_prompt(True)
@@ -2009,7 +2021,7 b' want to merge them back into the new files.""" % locals()'
 
         try:
             code = self.compile(source,filename,symbol)
-        except (OverflowError, SyntaxError, ValueError):
+        except (OverflowError, SyntaxError, ValueError, TypeError):
             # Case 1
             self.showsyntaxerror(filename)
             return None
@@ -2053,6 +2065,7 b' want to merge them back into the new files.""" % locals()'
         outflag = 1  # happens in more places, so it's easier as default
         try:
             try:
+                self.hooks.pre_runcode_hook()
                 # Embedded instances require separate global/local namespaces
                 # so they can see both the surrounding (local) namespace and
                 # the module-level globals when called inside another function.

IPython/ipmaker.py

@@ -58,6 +58,14 b' from IPython.iplib import InteractiveShell'
 from IPython.usage import cmd_line_usage,interactive_usage
 from IPython.genutils import *
 
+def force_import(modname):
+    if modname in sys.modules:
+        print "reload",modname
+        reload(sys.modules[modname])
+    else:
+        __import__(modname)
+        
+
 #-----------------------------------------------------------------------------
 def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,
                  rc_override=None,shell_class=InteractiveShell,
@@ -95,9 +103,12 b' def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,'
                      embedded=embedded,**kw)
 
     # Put 'help' in the user namespace
-    from site import _Helper
+    try:
+        from site import _Helper
+        IP.user_ns['help'] = _Helper()
+    except ImportError:
+        warn('help() not available - check site.py')
     IP.user_config_ns = {}
-    IP.user_ns['help'] = _Helper()
 
 
     if DEVDEBUG:
@@ -176,10 +187,10 b" object? -> Details about 'object'. ?object also works, ?? prints more."
 
     # Options that can *only* appear at the cmd line (not in rcfiles).
     
-    # The "ignore" option is a kludge so that Emacs buffers don't crash, since
-    # the 'C-c !' command in emacs automatically appends a -i option at the end.
     cmdline_only = ('help interact|i ipythondir=s Version upgrade '
-                    'gthread! qthread! q4thread! wthread! tkthread! pylab! tk!')
+                    'gthread! qthread! q4thread! wthread! tkthread! pylab! tk! '
+                    # 'twisted!'  # disabled for now.
+                    )
 
     # Build the actual name list to be used by DPyGetOpt
     opts_names = qw(cmdline_opts) + qw(cmdline_only)
@@ -203,7 +214,7 b" object? -> Details about 'object'. ?object also works, ?? prints more."
                       editor = '0',
                       gthread = 0,
                       help = 0,
-                      interact = 1,
+                      interact = 0,
                       ipythondir = ipythondir_def,
                       log = 0,
                       logfile = '',
@@ -237,6 +248,7 b" object? -> Details about 'object'. ?object also works, ?? prints more."
                       system_verbose = 0,
                       term_title = 1,
                       tk = 0,
+                      #twisted= 0,  # disabled for now
                       upgrade = 0,
                       Version = 0,
                       wildcards_case_sensitive = 1,
@@ -633,15 +645,17 b" object? -> Details about 'object'. ?object also works, ?? prints more."
     if opts_all.profile and not profile_handled_by_legacy:
         profmodname = 'ipy_profile_' + opts_all.profile
         try:
-            __import__(profmodname)
+            
+            force_import(profmodname)
         except:
             IP.InteractiveTB()
             print "Error importing",profmodname,"- perhaps you should run %upgrade?"
             import_fail_info(profmodname)
     else:
-        import ipy_profile_none
-    try:    
-        import ipy_user_conf
+        force_import('ipy_profile_none')
+    try:
+            
+        force_import('ipy_user_conf')
         
     except:
         conf = opts_all.ipythondir + "/ipy_user_conf.py"

IPython/platutils_posix.py

@@ -23,12 +23,17 b' __license__ = Release.license'
 import sys
 import os
 
+ignore_termtitle = False
 
 def _dummy_op(*a, **b):
     """ A no-op function """
 
 def _set_term_title_xterm(title):
     """ Change virtual terminal title in xterm-workalikes """
+
+    if ignore_termtitle:
+        return
+    
     sys.stdout.write('\033]%d;%s\007' % (0,title))
 
 
@@ -37,4 +42,6 b" if os.environ.get('TERM','') == 'xterm':"
 else:
     set_term_title = _dummy_op
 
-    
+def freeze_term_title():
+    global ignore_termtitle
+    ignore_termtitle = True

IPython/platutils_win32.py

@@ -50,4 +50,7 b' def set_term_title(title):'
         return
     _set_term_title(title)
 
+def freeze_term_title():
+    global ignore_termtitle
+    ignore_termtitle = 1
 

IPython/ultraTB.py

@@ -377,8 +377,8 b' class ListTB(TBTools):'
         
     def __call__(self, etype, value, elist):
         Term.cout.flush()
-        Term.cerr.flush()
         print >> Term.cerr, self.text(etype,value,elist)
+        Term.cerr.flush()
 
     def text(self,etype, value, elist,context=5):
         """Return a color formatted string with the traceback info."""
@@ -855,8 +855,8 b' class VerboseTB(TBTools):'
         (etype, evalue, etb) = info or sys.exc_info()
         self.tb = etb
         Term.cout.flush()
-        Term.cerr.flush()
         print >> Term.cerr, self.text(etype, evalue, etb)
+        Term.cerr.flush()
 
     # Changed so an instance can just be called as VerboseTB_inst() and print
     # out the right info on its own.
@@ -977,13 +977,13 b' class AutoFormattedTB(FormattedTB):'
         if out is None:
             out = Term.cerr
         Term.cout.flush()
-        out.flush()
         if tb_offset is not None:
             tb_offset, self.tb_offset = self.tb_offset, tb_offset
             print >> out, self.text(etype, evalue, etb)
             self.tb_offset = tb_offset
         else:
             print >> out, self.text(etype, evalue, etb)
+        out.flush()
         try:
             self.debugger()
         except KeyboardInterrupt:

MANIFEST.in

@@ -9,22 +9,23 b' graft setupext'
 graft IPython/UserConfig
 
 graft doc
+exclude doc/\#*
 exclude doc/*.1
-exclude doc/manual_base*
 exclude doc/ChangeLog.*
-exclude doc/\#*
-exclude doc/update_magic.sh
 exclude doc/update_version.sh
-exclude doc/manual_base*
-exclude doc/manual/WARNINGS
-exclude doc/manual/*.aux
-exclude doc/manual/*.log
-exclude doc/manual/*.out
-exclude doc/manual/*.pl
-exclude doc/manual/*.tex
+
+# There seems to be no way of excluding whole subdirectories, other than
+# manually excluding all their subdirs.  distutils really is horrible...
+exclude doc/attic/*
+exclude doc/build/doctrees/*
+exclude doc/build/html/_sources/*
+exclude doc/build/html/_static/*
+exclude doc/build/html/*
+exclude doc/build/latex/*
 
 global-exclude *~
 global-exclude *.flc
 global-exclude *.pyc
 global-exclude .dircopy.log
 global-exclude .svn
+global-exclude .bzr

debian/changelog

@@ -1,8 +1,330 b''
+ipython (0.8.1-2) unstable; urgency=low
+
+  [ Piotr Ożarowski ]
+  * Homepage field added
+  * Rename XS-Vcs-* fields to Vcs-* (dpkg supports them now)
+  * Add 04_remove_shebang patch
+  * Removing lintian overrides, adding proper patches instead.
+
+  [ Bernd Zeimetz ]
+  * Replacing Recommends by Suggests to stop ipython from installing ~500MB
+    of dependencies. Thanks to Marcela Tiznado (Closes: #451887).
+
+ -- Bernd Zeimetz <[e-mail]>  Mon, 19 Nov 2007 19:10:14 +0100
+
+ipython (0.8.1-1) unstable; urgency=low
+
+  [ Bernd Zeimetz ]
+  * debian/control:
+     - adding python-matplotlib to Recommends because
+       it is needed to run ipython -pylab
+
+  [ Norbert Tretkowski ]
+  * New upstream release. (closes: #428398)
+
+  [ Reinhard Tartler ]
+  * Install ipython.el properly.
+
+ -- Norbert Tretkowski <[e-mail]>  Mon, 11 Jun 2007 20:05:30 +0200
+
+ipython (0.8.0-2) unstable; urgency=low
+
+  * debian/changelog:
+     - adding missing colons to Closes entries to fix two
+       lintian warnings
+  * debian/compat:
+     - bumping compat level to 5
+  * debian/control:
+     - adding XS-Vcs-Browser
+     - remove no longer needed X*-Python-Version fields
+     - moving python-pexpect from Recommends to Depends because
+       /usr/bin/irunner is not useable without it
+     - moving debhelper and dpatch from Build-Depends-Indep to
+       Build-Depends, fixing the following lintian errors:
+         - clean-should-be-satisfied-by-build-depends debhelper
+         - clean-should-be-satisfied-by-build-depends dpatch
+     - removing unnecessary Build-Depends-Indep on python-all-dev,
+       adding python to Build-Depends instead
+     - replacing python-central by python-support to be able to
+       fix #420134 without hassle
+     - adding ${misc:Depends}
+     - adding the missing identation for Homepage:
+     - adding cdbs as Build-Depends
+     - adding myself to Uploaders
+     - removing the short description from the long description
+  * debian/patches/03_ipy_gnuglobal.dpatch:
+     - fix the location of the global binary - we're not on windows
+  * debian/rules:
+     - removing old crust, using cdbs to make things clear again
+     - using python-support instead of python-central to make
+       modules for 2.5 avaiable now. (Closes: #420134)
+     - making sure the bogus /usr/IPython directory is not
+       included in the package again
+     - do not remove docs/ipython.el (Closes: #198505, #415427)
+  * adding lintian ovverrides for several scripts included in the
+    IPython/Extensions directory.
+  * adding a manpage for /usr/bin/irunner
+
+ -- Bernd Zeimetz <[e-mail]>  Tue, 24 Apr 2007 02:47:26 +0200
+
+ipython (0.8.0-1) unstable; urgency=low
+
+  * New upstream release. (closes: #419716)
+  * Removed patches merged upstream.
+
+ -- Norbert Tretkowski <[e-mail]>  Tue, 17 Apr 2007 20:26:43 +0200
+
+ipython (0.7.3-2) unstable; urgency=low
+
+  * Added a new patch from svn to fix jobctrl to work properly on posix.
+
+ -- Norbert Tretkowski <[e-mail]>  Thu, 21 Dec 2006 20:13:57 +0100
+
+ipython (0.7.3-1) unstable; urgency=low
+
+  * New upstream release.
+
+ -- Norbert Tretkowski <[e-mail]>  Mon, 18 Dec 2006 22:23:55 +0100
+
+ipython (0.7.3~rc2-1) experimental; urgency=low
+
+  * New upstream release candidate.
+
+ -- Norbert Tretkowski <[e-mail]>  Sat, 16 Dec 2006 02:20:13 +0100
+
+ipython (0.7.3~beta2-1) experimental; urgency=low
+
+  * New upstream beta release.
+
+ -- Norbert Tretkowski <[e-mail]>  Fri,  8 Dec 2006 08:02:16 +0100
+
+ipython (0.7.3~beta1-1) experimental; urgency=low
+
+  * New upstream beta release.
+  * Removed backported patch added in 0.7.2-5 to workaround bugs in python
+    2.3's inspect module.
+
+ -- Norbert Tretkowski <[e-mail]>  Wed, 29 Nov 2006 12:35:22 +0100
+
+ipython (0.7.2-6) UNRELEASED; urgency=low
+
+  * Added XS-Vcs-Svn field.
+
+ -- Piotr Ozarowski <[e-mail]>  Thu, 23 Nov 2006 14:44:43 +0100
+
+ipython (0.7.2-5) unstable; urgency=low
+
+  * Added a new patch from svn to workaround bugs in python 2.3's inspect
+    module. (closes: #374625)
+
+ -- Norbert Tretkowski <[e-mail]>  Thu, 10 Aug 2006 18:36:12 +0200
+
+ipython (0.7.2-4) unstable; urgency=low
+
+  * Fixed spelling error in description. (closes: #363976)
+  * Ack NMU 0.7.2-3.1, thanks Matthias. (closes: #377787)
+
+ -- Norbert Tretkowski <[e-mail]>  Tue,  1 Aug 2006 22:45:11 +0200
+
+ipython (0.7.2-3.1) unstable; urgency=medium
+
+  * NMU.
+  * Convert to updated Python policy. (closes: #377787)
+
+ -- Matthias Klose <[e-mail]>  Thu, 13 Jul 2006 17:42:06 +0000
+
+ipython (0.7.2-3ubuntu1) edgy; urgency=low
+
+  * Synchronize with Debian unstable.
+  * Convert to updated Python policy. Collapse all packages into one
+    ipython package, don't handle ipython using alternatives.
+
+ -- Matthias Klose <[e-mail]>  Tue, 11 Jul 2006 09:47:37 +0000
+
+ipython (0.7.2-3) unstable; urgency=low
+
+  * Removed alternative for irunner manpage.
+
+ -- Norbert Tretkowski <[e-mail]>  Sat, 17 Jun 2006 09:49:10 +0200
+
+ipython (0.7.2-2) unstable; urgency=medium
+
+  * Fixed conflict in irunner. (closes: #373874)
+  * Added recommendation for python-pexpect. (closes: #373794)
+
+ -- Norbert Tretkowski <[e-mail]>  Fri, 16 Jun 2006 10:43:45 +0200
+
+ipython (0.7.2-1) unstable; urgency=low
+
+  [ Piotr Ozarowski ]
+  * Added watch file.
+
+  [ Norbert Tretkowski ]
+  * New upstream release.
+
+ -- Norbert Tretkowski <[e-mail]>  Thu,  8 Jun 2006 23:36:03 +0200
+
+ipython (0.7.1.fix1+0.7.2.rc1-1) experimental; urgency=low
+
+  * New upstream release candidate.
+  * Updated Standards-Version to 3.7.2.0, no changes required.
+
+ -- Norbert Tretkowski <[e-mail]>  Sat, 27 May 2006 14:49:24 +0200
+
+ipython (0.7.1.fix1-2) unstable; urgency=low
+
+  * Set maintainer to Debian Python modules team and added myself to
+    uploaders.
+
+ -- Norbert Tretkowski <[e-mail]>  Sun, 16 Apr 2006 15:53:43 +0200
+
+ipython (0.7.1.fix1-1) unstable; urgency=low
+
+  * New upstream bugfix release.
+  * Removed backported patch which was added in 0.7.1-3 to catch
+    KeyboardInterrupt exceptions properly, it's part of this release.
+  * Fixed names of pdfs in doc-base file to shut up linda.
+
+ -- Norbert Tretkowski <[e-mail]>  Tue, 14 Feb 2006 23:51:17 +0100
+
+ipython (0.7.1-3) unstable; urgency=low
+
+  * Added a new patch from upstream to catch KeyboardInterrupt exceptions
+    properly.
+
+ -- Norbert Tretkowski <[e-mail]>  Mon, 30 Jan 2006 19:42:31 +0100
+
+ipython (0.7.1-2) unstable; urgency=low
+
+  * Really remove alternatives on purge, thanks Lars Wirzenius for finding
+    the problem. (closes: #317269)
+
+ -- Norbert Tretkowski <[e-mail]>  Sun, 29 Jan 2006 23:11:28 +0100
+
+ipython (0.7.1-1) unstable; urgency=low
+
+  * New upstream release.
+
+ -- Norbert Tretkowski <[e-mail]>  Tue, 24 Jan 2006 21:42:33 +0100
+
+ipython (0.7.0-2) unstable; urgency=low
+
+  * Fixed circular dependencies (closes: #341980)
+  * Added version to dependency on ipython dummy package. (closes: #320235)
+  * Removed python2.2 package, ipython now depends on python >= 2.3.
+  * Bumped up standards-version, no changes needed.
+
+ -- Norbert Tretkowski <[e-mail]>  Sat, 21 Jan 2006 23:27:53 +0100
+
+ipython (0.7.0-1) unstable; urgency=low
+
+  * New upstream release.
+  * Updated 01_docdir-base.dpatch and 02_profiler-message.dpatch.
+
+ -- Norbert Tretkowski <[e-mail]>  Sat, 21 Jan 2006 20:08:23 +0100
+
+ipython (0.6.15-2) unstable; urgency=low
+
+  * New maintainer, thanks Jack for your work.
+
+ -- Norbert Tretkowski <[e-mail]>  Sun, 28 Aug 2005 19:57:09 +0200
+
+ipython (0.6.15-1) unstable; urgency=low
+
+  * New upstream release.
+
+ -- Norbert Tretkowski <[e-mail]>  Thu,  2 Jun 2005 23:51:45 +0200
+
+ipython (0.6.14-1) unstable; urgency=low
+
+  * New upstream release.
+
+ -- Norbert Tretkowski <[e-mail]>  Tue, 31 May 2005 22:53:25 +0200
+
+ipython (0.6.13-1) unstable; urgency=low
+
+  * New upstream release.
+  * Removed backported patch which was added in 0.6.12-3 to fix misleading
+    prompt, it's part of this release.
+
+ -- Norbert Tretkowski <[e-mail]>  Fri, 15 Apr 2005 09:42:35 +0200
+
+ipython (0.6.12-4) unstable; urgency=medium
+
+  * Re-added python build-dependency, it got lost in 0.6.12-2.
+    (closes: #301636)
+
+ -- Norbert Tretkowski <[e-mail]>  Sun, 27 Mar 2005 14:28:26 +0200
+
+ipython (0.6.12-3) unstable; urgency=low
+
+  * Added a new patch from cvs to fix misleading prompt2. (closes: #300847)
+
+ -- Norbert Tretkowski <[e-mail]>  Sun, 27 Mar 2005 00:05:26 +0100
+
+ipython (0.6.12-2) unstable; urgency=low
+
+  * Added packages for python2.2 and python2.4, ipython package is now a dummy
+    package depending on ipython built for Debians default python.
+    (closes: #292537)
+  * Split out generic files into separate ipython-common package.
+  * Enhanced package descriptions.
+  * Removed CFLAGS settings from debian/rules, not required.
+  * Tweaked message displayed when profiler support is missing.
+  * Suggest the python-profiler package.
+
+ -- Norbert Tretkowski <[e-mail]>  Fri, 25 Mar 2005 20:24:36 +0100
+
+ipython (0.6.12-1) unstable; urgency=low
+
+  * New upstream release.
+  * Removed patch which was added in 0.6.5-1.1 to make profiling support
+    optional, it was merged upstream.
+
+ -- Norbert Tretkowski <[e-mail]>  Wed,  2 Mar 2005 12:15:09 +0100
+
+ipython (0.6.11-1) unstable; urgency=low
+
+  * New upstream release.
+    + Fixed broken profiling support unless -D is specified. (closes: #295779)
+  * Acknowledged NMUs. (closes: #206653, #294500, #294861, #280505)
+  * New co-maintainer, added myself to uploaders.
+
+ -- Norbert Tretkowski <[e-mail]>  Tue,  1 Mar 2005 12:40:33 +0100
+
+ipython (0.6.5-1.2) unstable; urgency=low
+
+  * Non-maintainer upload.
+  * Rebuild with a python version that is actually in Debian.
+
+ -- Wichert Akkerman <[e-mail]>  Thu, 17 Feb 2005 23:08:52 +0100
+
+ipython (0.6.5-1.1) unstable; urgency=low
+
+  * NMU to apply patch making profiling support optional (provided by
+    Torsten Marek). (closes: #294500)
+
+ -- Steven R. Baker <[e-mail]>  Thu, 17 Feb 2005 05:02:55 -0400
+
+ipython (0.6.5-1) unstable; urgency=low
+
+  * New upstream release
+
+ -- Jack Moffitt <[e-mail]>  Thu,  2 Dec 2004 15:49:27 -0700
+
+ipython (0.6.4-1.1) unstable; urgency=low
+
+  * NMU from BSP Frankfurt:
+    - Added Build-Depends on dpatch (Closes: #280505)
+
+ -- Joerg Jaspert <[e-mail]>  Sat, 27 Nov 2004 18:28:17 +0100
+
 ipython (0.6.4-1) unstable; urgency=low
 
-  * Fix dpatch dependency (Closes: #280505)
+  * New upstream release
+  * Updated debian/rules to use dpatch and added debian/patches/*
 
- -- Fernando Perez <[e-mail]> Wed Nov 17 22:54:23 MST 2004
+ -- Jack Moffitt <[e-mail]>  Tue,  9 Nov 2004 10:38:51 -0700
 
 ipython (0.6.3-1) unstable; urgency=low
 
@@ -27,8 +349,8 b' ipython (0.4.0-1.1) unstable; urgency=low'
 
 ipython (0.4.0-1) unstable; urgency=low
 
-  * New upstream release (Closes #195215)
-  * Updated Build-Depends (Closes #200021)
+  * New upstream release (Closes: #195215)
+  * Updated Build-Depends (Closes: #200021)
 
  -- Jack Moffitt <[e-mail]>  Fri, 25 Jul 2003 10:16:12 -0600
 

debian/compat

@@ -1,1 +1,1 b''
-4
+5

debian/control

@@ -1,21 +1,26 b''
 Source: ipython
-Section: devel
+Section: python
 Priority: optional
-Maintainer: Jack Moffitt <[e-mail]>
-Build-Depends-Indep: debhelper (>> 4.1.65), dpatch, python-dev
-Standards-Version: 3.6.1
+Maintainer: Debian Python Modules Team <[e-mail]>
+Uploaders: Norbert Tretkowski <[e-mail]>, Bernd Zeimetz <[e-mail]>
+Build-Depends: debhelper (>= 5.0.37.2), dpatch (>= 2.0.10), cdbs (>= 0.4.43), python, python-support (>= 0.4)
+Homepage: http://ipython.scipy.org/
+Vcs-Svn: svn://svn.debian.org/python-modules/packages/ipython/trunk/
+Vcs-Browser: http://svn.debian.org/wsvn/python-modules/packages/ipython/trunk/
+Standards-Version: 3.7.2.2
 
 Package: ipython
 Architecture: all
-Depends: ${python:Depends}
-Recommends: python-numeric, python-numeric-ext
-Description: An enhanced interactive Python shell
- IPython is an enhanced interactive Python shell.  It can be used as a
- replacement for the standard Python shell, or it can be used as a
- complete working environment for scientific computing (like Matlab or
- Mathematica) when paired with the standard Python scientific and
- numerical tools.  It supports dynamic object introspections, numbered
- input/output prompts, a macro system, session logging, session
- restoring, complete system shell access, verbose and colored
- traceback reports, auto-parentheses, auto-quoting, and is
- embeddedable in other Python programs.
+Depends: ${python:Depends}, ${misc:Depends}, python-pexpect
+Conflicts: python2.3-ipython, python2.4-ipython, ipython-common
+Replaces: python2.3-ipython, python2.4-ipython, ipython-common
+Suggests: python-profiler, python-numeric, python-numeric-ext, python-matplotlib
+Description: enhanced interactive Python shell
+ IPython can be used as a replacement for the standard Python shell,
+ or it can be used as a complete working environment for scientific
+ computing (like Matlab or Mathematica) when paired with the standard
+ Python scientific and numerical tools. It supports dynamic object
+ introspections, numbered input/output prompts, a macro system,
+ session logging, session restoring, complete system shell access,
+ verbose and colored traceback reports, auto-parentheses, auto-quoting,
+ and is embeddable in other Python programs.

debian/copyright

@@ -4,51 +4,15 b' Wed, 12 Mar 2003 20:38:14 -0700.'
 It was downloaded from http://ipython.scipy.org/
 
 Upstream Author: Fernando Perez <[e-mail]>,
-		 Janko Hauser <[e-mail]>,
+		 Janko Hauser <[e-mail]>,
 		 Nathaniel Gray <[e-mail]>
 
 Copyright:
 
-Most IPython code is copyright (C) 2001-2004 by Fernando Perez, Janko Hauser,
-and Nathaniel Gray.  All code is licensed under a BSD-type License except as
-explicitly mentioned below.  The full IPython license is:
-
-IPython is released under a BSD-type license.
-
-Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez <[e-mail]>.
-
-Copyright (c) 2001 Janko Hauser <[e-mail]> and Nathaniel Gray
-<[e-mail]>.
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-  a. Redistributions of source code must retain the above copyright notice,
-     this list of conditions and the following disclaimer.
-
-  b. Redistributions in binary form must reproduce the above copyright
-     notice, this list of conditions and the following disclaimer in the
-     documentation and/or other materials provided with the distribution.
-
-  c. Neither the name of the copyright holders nor the names of any
-     contributors to this software may be used to endorse or promote products
-     derived from this software without specific prior written permission.
-
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
+Most IPython code is copyright (C) 2001 by Fernando Perez, Janko
+Hauser, and Nathaniel Gray.  All code is licensed under the GNU Lesser
+General Public License (LGPL) except as explicitly mentioned below.
+Its full text is included in the file /usr/share/common-licenses/LGPL.
 
 DPyGetOpt.py is copyright (C) 2001 by Bill Bumgarner <[e-mail]>
 and is licensed under the MIT license, reproduced below:

debian/rules

@@ -1,98 +1,25 b''
 #!/usr/bin/make -f
-# Sample debian/rules that uses debhelper.
-# GNU copyright 1997 to 1999 by Joey Hess.
-
-# Uncomment this to turn on verbose mode.
-#export DH_VERBOSE=1
-
-
-
-
-CFLAGS = -Wall -g
-
-ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
-	CFLAGS += -O0
-else
-	CFLAGS += -O2
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-	INSTALL_PROGRAM += -s
-endif
-
-configure: configure-stamp
-configure-stamp:
-	dh_testdir
-
-	python setup.py config
-
-	touch configure-stamp
-
-
-build: build-stamp
-
-build-stamp: configure-stamp 
-	dh_testdir
-
-	python setup.py build
-
-	touch build-stamp
-
-clean:
-	dh_testdir
-	dh_testroot
-	rm -f build-stamp configure-stamp
-
-	-python setup.py clean --all
-	rm -f setupext/*.pyc
-
-	dh_clean
-
-install: build
-	dh_testdir
-	dh_testroot
-	dh_clean -k
-	dh_installdirs
-
-	python setup.py install --prefix $(CURDIR)/debian/ipython/usr
-
-	# remove extra license docs that get installed
-	rm -f $(CURDIR)/debian/ipython/usr/share/doc/ipython/COPYING
-	#rm -f $(CURDIR)/debian/ipython/usr/share/doc/ipython/GNU-LGPL
-
+# ipython debian/rules file
+DEB_PYTHON_SYSTEM=pysupport
+include /usr/share/cdbs/1/rules/debhelper.mk
+include /usr/share/cdbs/1/class/python-distutils.mk
+include /usr/share/cdbs/1/rules/dpatch.mk
+
+install/ipython::
+	# remove documentation
+	rm $(CURDIR)/debian/ipython/usr/share/doc/ipython/COPYING
+	rm $(CURDIR)/debian/ipython/usr/share/doc/ipython/ChangeLog
+	rm $(CURDIR)/debian/ipython/usr/share/doc/ipython/README_Windows.txt
+	rm $(CURDIR)/debian/ipython/usr/share/doc/ipython/pycon.ico
+	
 	# change permission on scripts
-	chmod 755 $(CURDIR)/debian/ipython/usr/share/doc/ipython/examples/example-embed.py	
-	chmod 755 $(CURDIR)/debian/ipython/usr/share/doc/ipython/examples/example-gnuplot.py
-
-binary-indep: build install
-	dh_testdir
-	dh_testroot
-	dh_installchangelogs doc/ChangeLog
-	dh_installdocs
-#	dh_installexamples
-	dh_install
-#	dh_installmenu
-#	dh_installdebconf	
-#	dh_installlogrotate
-#	dh_installemacsen
-#	dh_installpam
-#	dh_installmime
-#	dh_installinit
-#	dh_installcron
-#	dh_installinfo
-	dh_installman doc/ipython.1.gz doc/pycolor.1.gz
-	dh_compress
-	dh_fixperms
-	dh_python
-#	dh_makeshlibs
-	dh_installdeb
-#	dh_shlibdeps
-	dh_gencontrol
-	dh_md5sums
-	dh_builddeb
-
-# Build architecture-dependent files here.
-binary-arch: build install
-# We have nothing to do by default.
-
-binary: binary-indep binary-arch
-.PHONY: build clean binary-indep binary-arch binary install configure
+	chmod a-x $(CURDIR)/debian/ipython/usr/share/doc/ipython/examples/*
+	
+	# removing bogus usr/IPython directory
+	rm -rf $(CURDIR)/debian/ipython/usr/IPython
+
+binary-fixup/ipython::
+	# fix lintian warnings (see also patches/04_remove_shebang.dpatch)
+	chmod +x $(CURDIR)/debian/ipython/usr/share/python-support/ipython/IPython/upgrade_dir.py
+	chmod +x $(CURDIR)/debian/ipython/usr/share/python-support/ipython/IPython/Extensions/pickleshare.py
+	chmod +x $(CURDIR)/debian/ipython/usr/share/python-support/ipython/IPython/irunner.py

doc/ChangeLog

@@ -1,11 +1,232 b''
[phone]  *** Released version 0.8.4
+
[phone]  Fernando Perez  <[e-mail]>
+
+	* IPython/ipmaker.py (make_IPython): The -twisted option is fully
+	disabled.
+
+	* IPython/Shell.py (_select_shell): completely disable -twisted.
+	This code is of dubious quality and  normal users should not
+	encounter it until we can clarify things further, even under
+	win32.  Since we need a quick emergency 0.8.4 release, it is now
+	disabled completely.  Users who want to run it can use the
+	following command (it's easy to put it in an alias or script):
+	
+	python -c"from IPython import twshell;twshell.IPShellTwisted().mainloop()"
+
[phone]  Ville Vainio <[e-mail]>
+
+	* shell.py: disable -twisted on non-win32 platforms.
+	import sets module on python 2.3.
+
+	* ipy_profile_sh.py: disable ipy_signals. Now, ipython
+	is verified to work with python 2.3
+	
+	* Release.py: update version to 0.8.4 for quick point fix
+
[phone]  *** Released version 0.8.3
+
[phone]  Fernando Perez  <[e-mail]>
+
+	* ../win32_manual_post_install.py (run): Fix the windows installer
+	so the links to the docs are correct.
+
+	* IPython/ultraTB.py: flush stderr after writing to it to fix
+	problems with exception traceback ordering in some platforms.
+	Thanks to a report/fix by Jie Tang <jietang86-AT-gmail.com>.
+
+	* IPython/Magic.py (magic_cpaste): add stripping of continuation
+	prompts, feature requested by Stefan vdW.
+
+	* ../setup.py: updates to build and release tools in preparation
+	for 0.8.3 release.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* iplib.py, ipmaker.py: survive lack of doctest and site._Helper
+	for minimal environments (e.g. Maemo sdk python)
+
+	* Magic.py: cpaste strips whitespace before >>> (allow pasting
+	doctests)
+
+	* ipy_completers.py: cd completer now does recursive path expand
+	(old behaviour is buggy on some readline versions)
+
[phone]  Ville Vainio <[e-mail]>
+
+	* Extensions/ipy_greedycompleter.py: 
+	New extension that enables a bit more "relaxed" tab 
+	completer that evaluates code without safety checks
+	(i.e. there can be side effects like function calls)
+
[phone]  Ville Vainio <[e-mail]>
+
+	* Extensions/ipy_lookfor.py: add %lookfor magic command
+	(search docstrings for words) by Pauli Virtanen. Close #245.
+
+	* Extension/ipy_jot.py: %jot and %read magics, analogous
+	to %store but you can specify some notes. Not read 
+	in automatically on startup, you need %read.
+	Contributed by Yichun Wei.
+
[phone]  Fernando Perez  <[e-mail]>
+
+	* IPython/genutils.py (page): apply workaround to curses bug that
+	can leave terminal corrupted after a call to initscr().
+
[phone]  Ville Vainio <[e-mail]>
+
+	* genutils.py: SList.grep supports 'field' argument
+
+	* ipy_completers.py: module completer looks inside
+	.egg zip files (patch by mc). Close #196.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* deep_reload.py: do not crash on from __future__ import 
+	absolute_import. Close #244.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipy_winpdb.py: New extension for winpdb integration.  %wdb
+	test.py is winpdb equivalent of %run -d test.py.  winpdb is a
+	crossplatform remote GUI debugger based on wxpython.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipython.rst, do_sphinx.py: New documentation base, based on
+	reStucturedText and Sphinx (html/pdf generation).  The old Lyx
+	based documentation will not be updated anymore.
+
+	* jobctrl.py: Use shell in Popen for 'start' command (in windows).
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipython.rst, do_sphinx.py: New documentation base, based on
+	reStucturedText and Sphinx (html/pdf generation).  The old Lyx
+	based documentation will not be updated anymore.
+
+	ipython.rst has up to date documentation on matters that were not
+	documented at all, and it also removes various
+	misdocumented/deprecated features.
+	
[phone]  Ville Vainio <[e-mail]>
+
+	* Shell.py: Merge mtexp branch:
+	https://code.launchpad.net/~ipython/ipython/mtexp
+
+	Privides simpler and more robust MTInteractiveShell that won't
+	deadlock, even when the worker thread (GUI) stops doing runcode()
+	regularly. r71.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* twshell.py: New shell that runs IPython code in Twisted reactor.
+	Launch by doing ipython -twisted. r67.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* Magic.py: %rehashx works correctly when shadowed system commands
+	have upper case characters (e.g. Print.exe). r64.
+
+	* ipy_bzr.py, ipy_app_completers.py: new bzr completer that also
+	knows options to commands, based on bzrtools. Uses bzrlib
+	directly. r66.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* make_tarball.py: Fixed for bzr.
+
+	* ipapi.py: Better _ip.runlines() script cleanup. r56,r79.
+
+	 * ipy_vimserver.py, ipy.vim: New extension for vim server mode,
+	 by Erich Heine.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipmaker.py: Force (reload?) import of ipy_user_conf and
+	ipy_profile_foo, so that embedded instances can be relaunched and
+	configuration is still done. r50
+
+	* ipapi.py, test_embed.py: Allow specifying shell class in
+	launch_new_instance & make_new instance. Use this in
+	test_embed.py. r51.
+
+	test_embed.py is also a good and simple demo of embedding IPython.
+	
+
[phone]  Ville Vainio <[e-mail]>
+
+	* tool/update_revnum.py: Change to bzr revisioning scheme in 
+	revision numbers.
+
+	* Shell.py: Threading improvements:
+
+	In multithreaded shells, do not hang on macros and o.autoexec
+	commands (or anything executed with _ip.runlines()) anymore. Allow
+	recursive execution of IPython code in
+	MTInteractiveShell.runsource by checking if we are already in
+	worker thread, and execute code directly if we are. r48.
+
+	MTInteractiveShell.runsource: execute code directly if worker
+	thread is not running yet (this is the case in config files). r49.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipy_profile_sh.py: You can now use $LA or LA() to refer to last
+	argument of previous command in sh profile. Similar to bash '!$'.
+	LA(3) or $LA(3) stands for last argument of input history command 
+	3.
+
+	* Shell.py: -pylab names don't clutter %whos listing.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipy_autoreload.py: new extension (by Pauli Virtanen) for 
+	autoreloading modules; try %autoreload and %aimport. Close #154.
+	Uses the new pre_runcode_hook.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* platutils_posix.py: freeze_term_title works
+
[phone]  Ville Vainio <[e-mail]>
+
+	* Magic.py: %quickref does not crash with empty docstring
+
[phone]  Ville Vainio <[e-mail]>
+
+	* completer.py: do not treat [](){} as protectable chars anymore,
+	close #233.
+
+	* completer.py: do not treat [](){} as protectable chars anymore
+	
+	* magic.py, test_cpaste.py: Allow different prefix for pasting 
+	from email
+
[phone]  Ville Vainio <[e-mail]>
+
+	* Switched over to Launchpad/bzr as primary VCS.
+
[phone]  Ville Vainio <[e-mail]>
+
+	* ipapi.py: _ip.runlines() is now much more liberal about 
+	indentation - it cleans up the scripts it gets
+	
[phone]  Ville Vainio <[e-mail]>
+
+	* Extensions/ipy_leo.py: created 'ILeo' IPython-Leo bridge.
+	Changes to it (later on) are too numerous to list in ChangeLog
+	until it stabilizes
+	
 2008-02-07  Darren Dale <[e-mail]>
 
-        * IPython/Shell.py: Call QtCore.pyqtRemoveInputHook() when creating
-        an IPShellQt4. PyQt4-4.2.1 and later uses PyOS_InputHook to improve 
-        interaction in the interpreter (like Tkinter does), but it seems to 
-        partially interfere with the IPython implementation and exec_()
-        still seems to block. So we disable the PyQt implementation and
-        stick with the IPython one for now.
+	* IPython/Shell.py: Call QtCore.pyqtRemoveInputHook() when creating
+	an IPShellQt4. PyQt4-4.2.1 and later uses PyOS_InputHook to improve 
+	interaction in the interpreter (like Tkinter does), but it seems to 
+	partially interfere with the IPython implementation and exec_()
+	still seems to block. So we disable the PyQt implementation and
+	stick with the IPython one for now.
 
 2008-02-02  Walter Doerwald  <[e-mail]>
 

doc/examples/extension.py

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

doc/examples/ipython_here_shell_extension.reg

@@ -1,6 +1,6 b''
- Windows Registry Editor Version 5.00
-
-[HKEY_CLASSES_ROOT\Directory\shell\IPython here]
-
-[HKEY_CLASSES_ROOT\Directory\shell\IPython here\Command]
+ Windows Registry Editor Version 5.00
+
+[HKEY_CLASSES_ROOT\Directory\shell\IPython here]
+
+[HKEY_CLASSES_ROOT\Directory\shell\IPython here\Command]
 @="cmd.exe /C ipython.py -p sh -i -c \"%cd %1\""
  No newline at end of file

doc/ipython.1

@@ -36,11 +36,11 b' The following special options are ONLY valid at the beginning of the command'
 line, and not later.  This is because they control the initialization of
 ipython itself, before the normal option-handling mechanism is active.
 .TP
-.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab
+.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab, \-twisted
 Only ONE of these can be given, and it can only be given as the first option
 passed to IPython (it will have no effect in any other position).  They provide
-threading support for the GTK, QT3, QT4 and WXWidgets toolkits, and for the
-matplotlib library.
+threading support for the GTK, QT3, QT4 and WXWidgets toolkits, for the
+matplotlib library and Twisted reactor.
 .br
 .sp 1
 With any of the first four options, IPython starts running a separate thread
@@ -56,6 +56,10 b' request a specific version of wx to be used. This requires that you have the'
 distributions.
 .br
 .sp 1
+If \-twisted is given, IPython start a Twisted reactor and runs IPython mainloop
+in a dedicated thread, passing commands to be run inside the Twisted reactor. 
+.br
+.sp 1
 If \-pylab is given, IPython loads special support for the matplotlib library
 (http://matplotlib.sourceforge.net), allowing interactive usage of any of its
 backends as defined in the user's .matplotlibrc file.  It automatically

exesetup.py

@@ -1,106 +1,106 b''
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-r"""Setup script for exe distribution of IPython (does not require python).
-
-- Requires py2exe
-
-- install pyreadline *package dir* in ipython root directory by running:
-  
-svn co http://ipython.scipy.org/svn/ipython/pyreadline/branches/maintenance_1.3/pyreadline/  
-wget http://ipython.scipy.org/svn/ipython/pyreadline/branches/maintenance_1.3/readline.py
-
-OR (if you want the latest trunk):  
-  
-svn co http://ipython.scipy.org/svn/ipython/pyreadline/trunk/pyreadline
-
-- Create the distribution in 'dist' by running "python exesetup.py py2exe"
-
-- Run ipython.exe to go.
-
-"""
-
-#*****************************************************************************
-#       Copyright (C) 2001-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.
-#*****************************************************************************
-
-# Stdlib imports
-import os
-import sys
-
-from glob import glob
-
-
-# A few handy globals
-isfile = os.path.isfile
-pjoin = os.path.join
-
-from distutils.core import setup
-from distutils import dir_util
-import py2exe
-
-# update the manuals when building a source dist
-# Release.py contains version, authors, license, url, keywords, etc.
-execfile(pjoin('IPython','Release.py'))
-
-# A little utility we'll need below, since glob() does NOT allow you to do
-# exclusion on multiple endings!
-def file_doesnt_endwith(test,endings):
-    """Return true if test is a file and its name does NOT end with any
-    of the strings listed in endings."""
-    if not isfile(test):
-        return False
-    for e in endings:
-        if test.endswith(e):
-            return False
-    return True
-
-
-egg_extra_kwds = {}
-
-# Call the setup() routine which does most of the work
-setup(name             = name,
-    options   = {
-    'py2exe': {
-        'packages' : ['IPython', 'IPython.Extensions', 'IPython.external',
-                      'pyreadline'],
-        'excludes' : ["Tkconstants","Tkinter","tcl",'IPython.igrid','wx',
-                      'wxPython','igrid', 'PyQt4', 'zope', 'Zope', 'Zope2',
-                      '_curses','enthought.traits','gtk','qt', 'pydb','idlelib',                      
-                      ]
-                    
-                     }
-    },
-    version          = version,
-    description      = description,
-    long_description = long_description,
-    author           = authors['Fernando'][0],
-    author_email     = authors['Fernando'][1],
-    url              = url,
-    download_url     = download_url,
-    license          = license,
-    platforms        = platforms,
-    keywords         = keywords,
-    console          = ['ipykit.py'],
-    
-    # extra params needed for eggs
-    **egg_extra_kwds                        
-    )
-
-minimal_conf = """
-import IPython.ipapi
-ip = IPython.ipapi.get()
-
-ip.load('ipy_kitcfg')
-import ipy_profile_sh
-"""
-
-if not os.path.isdir("dist/_ipython"):
-    print "Creating simple _ipython dir"
-    os.mkdir("dist/_ipython")
-    open("dist/_ipython/ipythonrc.ini","w").write("# intentionally blank\n")
-    open("dist/_ipython/ipy_user_conf.py","w").write(minimal_conf)
-    if os.path.isdir('bin'):
-        dir_util.copy_tree('bin','dist/bin')
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+r"""Setup script for exe distribution of IPython (does not require python).
+
+- Requires py2exe
+
+- install pyreadline *package dir* in ipython root directory by running:
+  
+svn co http://ipython.scipy.org/svn/ipython/pyreadline/branches/maintenance_1.3/pyreadline/  
+wget http://ipython.scipy.org/svn/ipython/pyreadline/branches/maintenance_1.3/readline.py
+
+OR (if you want the latest trunk):  
+  
+svn co http://ipython.scipy.org/svn/ipython/pyreadline/trunk/pyreadline
+
+- Create the distribution in 'dist' by running "python exesetup.py py2exe"
+
+- Run ipython.exe to go.
+
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2001-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.
+#*****************************************************************************
+
+# Stdlib imports
+import os
+import sys
+
+from glob import glob
+
+
+# A few handy globals
+isfile = os.path.isfile
+pjoin = os.path.join
+
+from distutils.core import setup
+from distutils import dir_util
+import py2exe
+
+# update the manuals when building a source dist
+# Release.py contains version, authors, license, url, keywords, etc.
+execfile(pjoin('IPython','Release.py'))
+
+# A little utility we'll need below, since glob() does NOT allow you to do
+# exclusion on multiple endings!
+def file_doesnt_endwith(test,endings):
+    """Return true if test is a file and its name does NOT end with any
+    of the strings listed in endings."""
+    if not isfile(test):
+        return False
+    for e in endings:
+        if test.endswith(e):
+            return False
+    return True
+
+
+egg_extra_kwds = {}
+
+# Call the setup() routine which does most of the work
+setup(name             = name,
+    options   = {
+    'py2exe': {
+        'packages' : ['IPython', 'IPython.Extensions', 'IPython.external',
+                      'pyreadline'],
+        'excludes' : ["Tkconstants","Tkinter","tcl",'IPython.igrid','wx',
+                      'wxPython','igrid', 'PyQt4', 'zope', 'Zope', 'Zope2',
+                      '_curses','enthought.traits','gtk','qt', 'pydb','idlelib',                      
+                      ]
+                    
+                     }
+    },
+    version          = version,
+    description      = description,
+    long_description = long_description,
+    author           = authors['Fernando'][0],
+    author_email     = authors['Fernando'][1],
+    url              = url,
+    download_url     = download_url,
+    license          = license,
+    platforms        = platforms,
+    keywords         = keywords,
+    console          = ['ipykit.py'],
+    
+    # extra params needed for eggs
+    **egg_extra_kwds                        
+    )
+
+minimal_conf = """
+import IPython.ipapi
+ip = IPython.ipapi.get()
+
+ip.load('ipy_kitcfg')
+import ipy_profile_sh
+"""
+
+if not os.path.isdir("dist/_ipython"):
+    print "Creating simple _ipython dir"
+    os.mkdir("dist/_ipython")
+    open("dist/_ipython/ipythonrc.ini","w").write("# intentionally blank\n")
+    open("dist/_ipython/ipy_user_conf.py","w").write(minimal_conf)
+    if os.path.isdir('bin'):
+        dir_util.copy_tree('bin','dist/bin')

ipykit.py

@@ -1,21 +1,21 b''
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-""" IPykit launcher
-
-w/o args, this launches a full ipykit session.
-
-If the first arg is a .py script, it will be run WITHOUT ipython,
-to facilitate running python scripts almost normally on machines w/o python
-in their own process (as opposed to %run).
-
-"""
-
-import sys
-if len(sys.argv) > 1 and sys.argv[1].endswith('.py'):
-    # shortcut for running ipykit.exe directly on a .py file - do not bother
-    # starting ipython, just handle as normal python scripts
-    sys.argv = sys.argv[1:]
-    execfile(sys.argv[0])
-else:
-    import IPython  
-    IPython.Shell.start().mainloop()
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+""" IPykit launcher
+
+w/o args, this launches a full ipykit session.
+
+If the first arg is a .py script, it will be run WITHOUT ipython,
+to facilitate running python scripts almost normally on machines w/o python
+in their own process (as opposed to %run).
+
+"""
+
+import sys
+if len(sys.argv) > 1 and sys.argv[1].endswith('.py'):
+    # shortcut for running ipykit.exe directly on a .py file - do not bother
+    # starting ipython, just handle as normal python scripts
+    sys.argv = sys.argv[1:]
+    execfile(sys.argv[0])
+else:
+    import IPython  
+    IPython.Shell.start().mainloop()

scripts/ipython

@@ -23,5 +23,5 b' this mode, there is no way to pass IPython any command-line options, as those'
 are trapped first by Python itself.
 """
 
-import IPython
+import IPython.Shell
 IPython.Shell.start().mainloop()

scripts/ipython_win_post_install.py

@@ -60,11 +60,11 b' def install():'
     mkshortcut(python,'IPython scipy profile',f,a)
 
     # Create documentation shortcuts ...    
-    t = prefix + r'\share\doc\ipython-%s\manual.pdf' % version
+    t = prefix + r'\share\doc\ipython\manual\ipython.pdf'
     f = ip_dir + r'\Manual in PDF.lnk'
     mkshortcut(t,r'IPython Manual - PDF-Format',f)
 
-    t = prefix + r'\share\doc\ipython-%s\manual\manual.html' % version
+    t = prefix + r'\share\doc\ipython\manual\ipython.html'
     f = ip_dir + r'\Manual in HTML.lnk'
     mkshortcut(t,'IPython Manual - HTML-Format',f)
 

setup.py

@@ -4,7 +4,7 b''
 
 Under Posix environments it works like a typical setup.py script. 
 Under Windows, the command sdist is not supported, since IPython 
-requires utilities, which are not available under Windows."""
+requires utilities which are not available under Windows."""
 
 #*****************************************************************************
 #       Copyright (C) 2001-2005 Fernando Perez <[e-mail]>
@@ -18,15 +18,41 b' import os'
 import sys
 
 from glob import glob
+
+# BEFORE importing distutils, remove MANIFEST. distutils doesn't properly
+# update it when the contents of directories change.
+if os.path.exists('MANIFEST'): os.remove('MANIFEST')
+
+from distutils.core import setup
 from setupext import install_data_ext
 
+# Local imports
+from IPython.genutils import target_update
+
 # A few handy globals
 isfile = os.path.isfile
 pjoin = os.path.join
 
-# BEFORE importing distutils, remove MANIFEST. distutils doesn't properly
-# update it when the contents of directories change.
-if os.path.exists('MANIFEST'): os.remove('MANIFEST')
+##############################################################################
+# Utility functions
+def oscmd(s):
+    print ">", s
+    os.system(s)
+
+# A little utility we'll need below, since glob() does NOT allow you to do
+# exclusion on multiple endings!
+def file_doesnt_endwith(test,endings):
+    """Return true if test is a file and its name does NOT end with any
+    of the strings listed in endings."""
+    if not isfile(test):
+        return False
+    for e in endings:
+        if test.endswith(e):
+            return False
+    return True
+
+###############################################################################
+# Main code begins
 
 if os.name == 'posix':
     os_name = 'posix'
@@ -36,43 +62,31 b' else:'
     print 'Unsupported operating system:',os.name
     sys.exit(1)
 
-# Under Windows, 'sdist' is not supported, since it requires lyxport (and
-# hence lyx,perl,latex,pdflatex,latex2html,sh,...)
+# Under Windows, 'sdist' has not been supported.  Now that the docs build with
+# Sphinx it might work, but let's not turn it on until someone confirms that it
+# actually works.
 if os_name == 'windows' and 'sdist' in sys.argv:
     print 'The sdist command is not available under Windows.  Exiting.'
     sys.exit(1)
 
-from distutils.core import setup
-
 # update the manuals when building a source dist
 if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'):
-    from IPython.genutils import target_update
-    # list of things to be updated. Each entry is a triplet of args for
+    import textwrap
+
+    # List of things to be updated. Each entry is a triplet of args for
     # target_update()
-    to_update = [('doc/magic.tex',
-                  ['IPython/Magic.py'],
-                  "cd doc && ./update_magic.sh" ),
-                 
-                 ('doc/manual.lyx',
-                  ['IPython/Release.py','doc/manual_base.lyx'],
-                  "cd doc && ./update_version.sh" ),
-                 
-                 ('doc/manual/manual.html',
-                  ['doc/manual.lyx',
-                   'doc/magic.tex',
-                   'doc/examples/example-gnuplot.py',
-                   'doc/examples/example-embed.py',
-                   'doc/examples/example-embed-short.py',
-                   'IPython/UserConfig/ipythonrc',
-                   ],
-                  "cd doc && "
-                  "lyxport -tt --leave --pdf "
-                  "--html -o '-noinfo -split +1 -local_icons' manual.lyx"),
+    to_update = [ # The do_sphinx scripts builds html and pdf, so just one
+                  # target is enough to cover all manual generation
+                 ('doc/manual/ipython.pdf',
+                  ['IPython/Release.py','doc/source/ipython.rst'],
+                  "cd doc && python do_sphinx.py" ),
+
+                  # FIXME - Disabled for now: we need to redo an automatic way
+                  # of generating the magic info inside the rst.                
+                  #('doc/magic.tex',
+                  #['IPython/Magic.py'],
+                  #"cd doc && ./update_magic.sh" ),
                  
-                 ('doc/new_design.pdf',
-                  ['doc/new_design.lyx'],
-                  "cd doc && lyxport -tt --pdf new_design.lyx"),
-
                  ('doc/ipython.1.gz',
                   ['doc/ipython.1'],
                   "cd doc && gzip -9c ipython.1 > ipython.1.gz"),
@@ -81,45 +95,33 b" if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'):"
                   ['doc/pycolor.1'],
                   "cd doc && gzip -9c pycolor.1 > pycolor.1.gz"),
                  ]
-    for target in to_update:
-        target_update(*target)
+
+    [ target_update(*t) for t in to_update ]
 
 # Release.py contains version, authors, license, url, keywords, etc.
 execfile(pjoin('IPython','Release.py'))
 
-# A little utility we'll need below, since glob() does NOT allow you to do
-# exclusion on multiple endings!
-def file_doesnt_endwith(test,endings):
-    """Return true if test is a file and its name does NOT end with any
-    of the strings listed in endings."""
-    if not isfile(test):
-        return False
-    for e in endings:
-        if test.endswith(e):
-            return False
-    return True
-
 # I can't find how to make distutils create a nested dir. structure, so
 # in the meantime do it manually. Butt ugly.
 # Note that http://www.redbrick.dcu.ie/~noel/distutils.html, ex. 2/3, contain
 # information on how to do this more cleanly once python 2.4 can be assumed.
 # Thanks to Noel for the tip.
-docdirbase  = 'share/doc/ipython-%s' % version
+docdirbase  = 'share/doc/ipython'
 manpagebase = 'share/man/man1'
 
 # We only need to exclude from this things NOT already excluded in the
 # MANIFEST.in file.
 exclude     = ('.sh','.1.gz')
 docfiles    = filter(lambda f:file_doesnt_endwith(f,exclude),glob('doc/*'))
-
 examfiles   = filter(isfile, glob('doc/examples/*.py'))
-manfiles    = filter(isfile, glob('doc/manual/*.html')) + \
-              filter(isfile, glob('doc/manual/*.css')) + \
-              filter(isfile, glob('doc/manual/*.png'))
+manfiles    = filter(isfile, glob('doc/manual/*'))
+manstatic   = filter(isfile, glob('doc/manual/_static/*'))
 manpages    = filter(isfile, glob('doc/*.1.gz'))
+
 cfgfiles    = filter(isfile, glob('IPython/UserConfig/*'))
 scriptfiles = filter(isfile, ['scripts/ipython','scripts/pycolor',
                               'scripts/irunner'])
+
 igridhelpfiles = filter(isfile, glob('IPython/Extensions/igrid_help.*'))
 
 # Script to be run by the windows binary installer after the default setup
@@ -135,8 +137,8 b" if 'bdist_wininst' in sys.argv:"
 datafiles = [('data', docdirbase, docfiles),
              ('data', pjoin(docdirbase, 'examples'),examfiles),
              ('data', pjoin(docdirbase, 'manual'),manfiles),
+             ('data', pjoin(docdirbase, 'manual/_static'),manstatic),
              ('data', manpagebase, manpages),
-             ('lib', 'IPython/UserConfig', cfgfiles),
              ('data',pjoin(docdirbase, 'extensions'),igridhelpfiles),
              ]
 
@@ -150,14 +152,15 b" if 'setuptools' in sys.modules:"
             ]}
         }
     scriptfiles = []
-    # eggs will lack docs, eaxmples
+    # eggs will lack docs, examples
     datafiles = []
-    
-    #datafiles = [('lib', 'IPython/UserConfig', cfgfiles)]
 else:
+    # Normal, non-setuptools install
     egg_extra_kwds = {}
-
-
+    # package_data of setuptools was introduced to distutils in 2.4
+    if sys.version_info < (2,4):
+        datafiles.append(('lib', 'IPython/UserConfig', cfgfiles))
+    
 # Call the setup() routine which does most of the work
 setup(name             = name,
       version          = version,
@@ -170,8 +173,11 b' setup(name = name,'
       license          = license,
       platforms        = platforms,
       keywords         = keywords,
-      packages         = ['IPython', 'IPython.Extensions', 'IPython.external'],
+      packages         = ['IPython', 'IPython.Extensions', 'IPython.external',
+                          'IPython.gui', 'IPython.gui.wx',
+                          'IPython.UserConfig'],
       scripts          = scriptfiles,
+      package_data     = {'IPython.UserConfig' : ['*'] },
       
       cmdclass         = {'install_data': install_data_ext},
       data_files       = datafiles,

test/test_embed.py

@@ -1,32 +1,48 b''
-""" An example of one way to embed IPython in your own application 
-
-This basically means starting up IPython with some of your programs objects visible in the IPython 
-user namespace.
-
-"""
-
-import sys
-sys.path.append('..')
-
-import IPython.ipapi
-
-my_ns = dict(a=10)
-
-ses = IPython.ipapi.make_session(my_ns)
-
-# Now get the ipapi instance, to be stored somewhere in your program for manipulation of the running 
-# IPython session. See http://ipython.scipy.org/moin/IpythonExtensionApi
-
-ip = ses.IP.getapi()   
-
-# let's play with the ipapi a bit, creating a magic function for a soon-to-be-started IPython
-def mymagic_f(self,s):
-    print "mymagic says",s
-
-ip.expose_magic("mymagic",mymagic_f)
-
-# And finally, start the IPython interaction! This will block until you say Exit.
-
-ses.mainloop()
-
-print "IPython session finished! namespace content:",my_ns
+""" An example of one way to embed IPython in your own application 
+
+This basically means starting up IPython with some of your programs objects visible in the IPython 
+user namespace.
+
+"""
+
+import sys
+sys.path.insert(1,'..')
+
+import IPython.ipapi
+
+
+
+def test_session(shellclass):
+    print "*****************\nLaunch shell for",shellclass
+    my_ns = dict(a=10)
+    ses = IPython.ipapi.make_session(my_ns, shellclass=shellclass)
+    
+    # Now get the ipapi instance, to be stored somewhere in your program for manipulation of the running 
+    # IPython session. See http://ipython.scipy.org/moin/IpythonExtensionApi
+    
+    ip = ses.IP.getapi()   
+    
+    # let's play with the ipapi a bit, creating a magic function for a soon-to-be-started IPython
+    def mymagic_f(self,s):
+        print "mymagic says",s
+    
+    ip.expose_magic("mymagic",mymagic_f)
+    
+    # And finally, start the IPython interaction! This will block until you say Exit.
+    
+    ses.mainloop()
+    
+    print "IPython session for shell ",shellclass," finished! namespace content:"
+    for k,v in my_ns.items():
+        print k,':',str(v)[:80].rstrip()
+    
+import  IPython.Shell    
+
+def do_test(arg_line):
+    test_session(IPython.Shell._select_shell(arg_line.split()))
+
+do_test('')
+do_test('ipython -gthread')
+do_test('ipython -q4thread')
+do_test('ipython -pylab')
+do_test('ipython -pylab -gthread')
  No newline at end of file

test/test_ipapi.py

@@ -1,54 +1,54 b''
-import sys
-sys.path.append('..')
-
-import IPython.ipapi
-IPython.ipapi.make_session()
-ip = IPython.ipapi.get()
-
-def test_runlines():
-    import textwrap
-    ip.runlines(['a = 10', 'a+=1'])
-    ip.runlines('assert a == 11\nassert 1')
-
-    assert ip.user_ns['a'] == 11
-    complex = textwrap.dedent("""\
-    if 1:
-        print "hello"
-        if 1:
-            print "world"
-        
-    if 1:
-        print "foo"
-    if 1:
-        print "bar"
-
-    if 1:
-        print "bar"
-    
-    """)
-
-    
-    ip.runlines(complex)
-    
-
-def test_db():
-    ip.db['__unittest_'] = 12
-    assert ip.db['__unittest_'] == 12
-    del ip.db['__unittest_']
-    assert '__unittest_' not in ip.db
-
-def test_defalias():
-    slot = [None]
-    # test callable alias
-    def cb(localip,s):
-        assert localip is ip
-        slot[0] = s
-    
-    ip.defalias('testalias', cb)
-    ip.runlines('testalias foo bar')
-    assert slot[0] == 'testalias foo bar'
-        
-
-test_runlines()
-test_db()
-test_defalias
+import sys
+sys.path.append('..')
+
+import IPython.ipapi
+IPython.ipapi.make_session()
+ip = IPython.ipapi.get()
+
+def test_runlines():
+    import textwrap
+    ip.runlines(['a = 10', 'a+=1'])
+    ip.runlines('assert a == 11\nassert 1')
+
+    assert ip.user_ns['a'] == 11
+    complex = textwrap.dedent("""\
+    if 1:
+        print "hello"
+        if 1:
+            print "world"
+        
+    if 1:
+        print "foo"
+    if 1:
+        print "bar"
+
+    if 1:
+        print "bar"
+    
+    """)
+
+    
+    ip.runlines(complex)
+    
+
+def test_db():
+    ip.db['__unittest_'] = 12
+    assert ip.db['__unittest_'] == 12
+    del ip.db['__unittest_']
+    assert '__unittest_' not in ip.db
+
+def test_defalias():
+    slot = [None]
+    # test callable alias
+    def cb(localip,s):
+        assert localip is ip
+        slot[0] = s
+    
+    ip.defalias('testalias', cb)
+    ip.runlines('testalias foo bar')
+    assert slot[0] == 'testalias foo bar'
+        
+
+test_runlines()
+test_db()
+test_defalias

tools/make_tarball.py

@@ -1,12 +1,11 b''
-import os,sys,shutil
+#!/usr/bin/env python
+"""Simple script to create a tarball with proper bzr version info.
+"""
 
-repo = "http://ipython.scipy.org/svn/ipython/ipython/branches/0.7.3"
-basename = 'ipython'
-workdir = './mkdist'
+import os,sys,shutil
 
-workdir = os.path.abspath(workdir)
+basever = '0.8.3'
 
-print "working at",workdir
 def oscmd(c):
     print ">",c
     s = os.system(c)
@@ -14,15 +13,24 b' def oscmd(c):'
         print "Error",s
         sys.exit(s)
 
+def verinfo():
+    
+    out = os.popen('bzr version-info')
+    pairs = (l.split(':',1) for l in out)
+    d = dict(((k,v.strip()) for (k,v) in pairs)) 
+    return d
+
+basename = 'ipython'
+
+#tarname = '%s.r%s.tgz' % (basename, ver)
+oscmd('python update_revnum.py')
+
+ver = verinfo()
 
-assert not os.path.isdir(workdir)
-os.mkdir(workdir)
-os.chdir(workdir)
+if ver['branch-nick'] == 'ipython':
+    tarname = 'ipython-%s.bzr.r%s.tgz' % (basever, ver['revno'])
+else:
+    tarname = 'ipython-%s.bzr.r%s.%s.tgz' % (basever, ver['revno'], ver['branch-nick'])
+    
+oscmd('bzr export ' + tarname)
 
-oscmd('svn export %s %s' % (repo,basename))
-ver = os.popen('svnversion ../..').read().strip()
-tarname = '%s.r%s.tgz' % (basename, ver)
-oscmd('tar czvf ../%s %s' % (tarname, basename))
-print "Produced: ",os.path.abspath('../' + tarname)
-os.chdir('/')
-shutil.rmtree(workdir)

tools/mkrel.py

@@ -1,11 +1,10 b''
-""" Create ipykit and exe installer
+#!/usr/bin/env python
+"""IPython release script
 
-requires py2exe
+Create ipykit and exe installer
 
+requires py2exe
 """
-#!/bin/sh
-# IPython release script
-
 
 import os
 import distutils.dir_util
@@ -19,21 +18,31 b' def c(cmd):'
 
 ipykit_name = "ipykit-%s" % version
 
-
 os.chdir('..')
 if os.path.isdir('dist'):
     distutils.dir_util.remove_tree('dist')
 if os.path.isdir(ipykit_name):
     distutils.dir_util.remove_tree(ipykit_name)
 
-c("python exesetup.py py2exe")
+if sys.platform == 'win32':
+    c("python exesetup.py py2exe")
 
-os.rename('dist',ipykit_name)
+    os.rename('dist',ipykit_name)
 
-c("zip -r %s.zip %s" % (ipykit_name, ipykit_name))
+    c("zip -r %s.zip %s" % (ipykit_name, ipykit_name))
+
+# Build source and binary distros
+c('./setup.py sdist --formats=gztar')
+
+c("python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/python2.4")
+c("python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5")
+
+# Build eggs
+c('python2.4 ./eggsetup.py bdist_egg')
+c('python2.5 ./eggsetup.py bdist_egg')
 
 c("python setup.py bdist_wininst --install-script=ipython_win_post_install.py")
 
-os.chdir("dist")
-#c("svn export http://ipython.scipy.org/svn/ipython/ipython/trunk ipython")
-#c("zip -r ipython_svn.zip ipython")
+os.chdir('tools')
+c('python make_tarball.py')
+

tools/release

@@ -4,6 +4,7 b''
 PYVER=`python -V 2>&1 | awk '{print $2}' | awk -F '.' '{print $1$2}' `
 version=`ipython -Version`
 ipdir=~/ipython/ipython
+ipbackupdir=~/ipython/backup
 
 echo
 echo "Releasing IPython version $version"
@@ -37,7 +38,8 b' rm -rf $ipdir/dist/*'
 
 # Perform local backup
 cd $ipdir/tools
-./bkp.sh
+./make_tarball.py
+mv ipython-*.tgz $ipbackupdir
 
 # Build source and binary distros
 cd $ipdir
@@ -50,8 +52,8 b' python2.4 ./setup.py bdist_rpm --binary-only --release=py24 --python=/usr/bin/py'
 python2.5 ./setup.py bdist_rpm --binary-only --release=py25 --python=/usr/bin/python2.5
 
 # Build eggs
-python2.4 ./eggsetup.py bdist_egg
-python2.5 ./eggsetup.py bdist_egg
+python2.4 ./setup_bdist_egg.py
+python2.5 ./setup_bdist_egg.py
 
 # Call the windows build separately, so that the extra Windows scripts don't
 # get pulled into Unix builds (setup.py has code which checks for
@@ -72,28 +74,28 b' echo "Uploading distribution files..."'
 scp * [e-mail]:www/dist/
 
 echo "Uploading backup files..."
-cd ~/ipython/backup
-scp `ls -1tr | tail -1` [e-mail]:www/backup/
+cd $ipbackupdir
+scp `ls -1tr *tgz | tail -1` [e-mail]:www/backup/
 
 echo "Updating webpage..."
 cd $ipdir/doc
 www=~/ipython/homepage
 cp ChangeLog NEWS $www
 rm -rf $www/doc/*
-cp -r manual.pdf manual/ $www/doc
+cp -r manual/ $www/doc
 cd $www
 ./update
 
 # Alert package maintainers
-echo "Alerting package maintainers..."
-maintainers='[e-mail] [e-mail] [e-mail] [e-mail] [e-mail] [e-mail]'
-#maintainers='[e-mail]'
-
-for email in $maintainers
-    do
-	echo "Emailing $email..."
-	mail -s "[Package maintainer notice] A new IPython is out. Version: $version" \
-    $email < NEWS
-    done
+#echo "Alerting package maintainers..."
+#maintainers='[e-mail] [e-mail] [e-mail] [e-mail] [e-mail] [e-mail]'
+# maintainers='[e-mail]'
+
+# for email in $maintainers
+#     do
+# 	echo "Emailing $email..."
+# 	mail -s "[Package maintainer notice] A new IPython is out. Version: $version" \
+#     $email < NEWS
+#     done
 
 echo "Done!"

tools/testrel

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

tools/update_revnum.py

@@ -2,13 +2,22 b''
 """ Change the revision number in Release.py """
 
 import os
-import re
+import re,pprint
 
-rev = os.popen('svnversion ..').read().strip()
+def verinfo():
+    
+    out = os.popen('bzr version-info')
+    pairs = (l.split(':',1) for l in out)
+    d = dict(((k,v.strip()) for (k,v) in pairs)) 
+    return d
 
-print "current rev is",rev
-assert ':' not in rev
+ver = verinfo()
 
-rfile = open('../IPython/Release.py').read()
-newcont = re.sub(r'revision\s*=.*', "revision = '%s'" % rev, rfile)
-open('../IPython/Release.py','w').write(newcont)
+pprint.pprint(ver)
+
+rfile = open('../IPython/Release.py','rb').read()
+newcont = re.sub(r'revision\s*=.*', "revision = '%s'" % ver['revno'], rfile)
+
+newcont = re.sub(r'^branch\s*=[^=].*', "branch = '%s'"  % ver['branch-nick'], newcont )
+
+open('../IPython/Release.py','wb').write(newcont)

win32_manual_post_install.py

@@ -104,8 +104,8 b' def run(wait=0):'
         os.mkdir(ip_prog_dir)
     os.chdir(ip_prog_dir)
 
-    man_pdf = doc_dir + r'\manual.pdf'
-    man_htm = doc_dir + r'\manual\manual.html'
+    man_pdf = doc_dir + r'\manual\ipython.pdf'
+    man_htm = doc_dir + r'\manual\ipython.html'
 
     make_shortcut('IPython.lnk',sys.executable, '"%s"' % ip_filename,
                   my_documents_dir,

doc/build_doc_instruction.txt

@@ -1,28 +0,0 b''
-How to generate IPython documentation
-=====================================
-
-The doc is written using lyx http://www.lyx.org, which is a gui for latex
-documents. LyX also requires a latex installation.
-
-The file manual_base.lyx is the template file that should be edited if you
-want to do changes to the docs.
-
-A final version is generated by running 
-
-./update_manual.py
-
-or 
-
-ipython update_manual.py
-
-(note that "python update_manual.py" won't work, it's an ipython script!)
-
-The script update_manual.py will insert the current version number into the
-template and also generate magic.tex, a file containing documentation for
-the doc strings of the magic commands.
-
-The script creates manual.lyx which can be opened by lyx to generate pdf or
-postscript versions of the docs.
-
-update_magic.sh and update_version.sh work too, but are slated for
-deprecation.

doc/manual_base.lyx

@@ -1,10507 +0,0 b''
-#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
-\lyxformat 245
-\begin_document
-\begin_header
-\textclass article
-\begin_preamble
-%\usepackage{ae,aecompl}
-\usepackage{color}
-
-% A few colors to replace the defaults for certain link types
-\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
-\definecolor{darkorange}{rgb}{.71,0.21,0.01}
-\definecolor{darkred}{rgb}{.52,0.08,0.01}
-\definecolor{darkgreen}{rgb}{.12,.54,.11}
-
-% Use and configure listings package for nicely formatted code
-\usepackage{listings}
-\lstset{
-  language=Python,
-  basicstyle=\small\ttfamily,
-  commentstyle=\ttfamily\color{blue},
-  stringstyle=\ttfamily\color{darkorange},
-  showstringspaces=false,
-  breaklines=true,
-  postbreak = \space\dots
-}
-
-\usepackage[%pdftex,  % needed for pdflatex
-  breaklinks=true,  % so long urls are correctly broken across lines
-  colorlinks=true,
-  urlcolor=blue,
-  linkcolor=darkred,
-  citecolor=darkgreen,
-  ]{hyperref}
-
-\usepackage{html}
-
-% This helps prevent overly long lines that stretch beyond the margins
-\sloppy
-
-% Define a \codelist command which either uses listings for latex, or
-% plain verbatim for html (since latex2html doesn't understand the 
-% listings package).
-\usepackage{verbatim}
-\newcommand{\codelist}[1] {
-\latex{\lstinputlisting{#1}}
-\html{\verbatiminput{#1}}
-}
-\end_preamble
-\language english
-\inputencoding latin1
-\fontscheme palatino
-\graphics default
-\paperfontsize 11
-\spacing single
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\cite_engine basic
-\use_bibtopic false
-\paperorientation portrait
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation skip
-\defskip medskip
-\quotes_language english
-\papercolumns 1
-\papersides 2
-\paperpagestyle fancy
-\tracking_changes false
-\output_changes true
-\end_header
-
-\begin_body
-
-\begin_layout Title
-IPython
-\newline
-
-\size larger
-An enhanced Interactive Python
-\size large
-
-\newline
-User Manual, v.
- __version__
-\end_layout
-
-\begin_layout Author
-Fernando P�rez
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-
-\size scriptsize
-Department of Applied Mathematics, University of Colorado at Boulder.
- 
-\family typewriter
-<[e-mail]>
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-latex{
-\end_layout
-
-\end_inset
-
-
-\begin_inset LatexCommand \tableofcontents{}
-
-\end_inset
-
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-html{
-\backslash
-bodytext{bgcolor=#ffffff}}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\newpage
-
-\end_layout
-
-\begin_layout Section
-Overview
-\end_layout
-
-\begin_layout Standard
-One of Python's most useful features is its interactive interpreter.
- This system allows very fast testing of ideas without the overhead of creating
- test files as is typical in most programming languages.
- However, the interpreter supplied with the standard Python distribution
- is somewhat limited for extended interactive use.
-\end_layout
-
-\begin_layout Standard
-IPython is a free software project (released under the BSD license) which
- tries to:
-\end_layout
-
-\begin_layout Enumerate
-Provide an interactive shell superior to Python's default.
- IPython has many features for object introspection, system shell access,
- and its own special command system for adding functionality when working
- interactively.
- It tries to be a very efficient environment both for Python code development
- and for exploration of problems using Python objects (in situations like
- data analysis).
-\end_layout
-
-\begin_layout Enumerate
-Serve as an embeddable, ready to use interpreter for your own programs.
- IPython can be started with a single call from inside another program,
- providing access to the current namespace.
- This can be very useful both for debugging purposes and for situations
- where a blend of batch-processing and interactive exploration are needed.
-\end_layout
-
-\begin_layout Enumerate
-Offer a flexible framework which can be used as the base environment for
- other systems with Python as the underlying language.
- Specifically scientific environments like Mathematica, IDL and Matlab inspired
- its design, but similar ideas can be useful in many fields.
-\end_layout
-
-\begin_layout Enumerate
-Allow interactive testing of threaded graphical toolkits.
- IPython has support for interactive, non-blocking control of GTK, Qt and
- WX applications via special threading flags.
- The normal Python shell can only do this for Tkinter applications.
-\end_layout
-
-\begin_layout Subsection
-Main features
-\end_layout
-
-\begin_layout Itemize
-Dynamic object introspection.
- One can access docstrings, function definition prototypes, source code,
- source files and other details of any object accessible to the interpreter
- with a single keystroke (`
-\family typewriter
-?
-\family default
-', and using `
-\family typewriter
-??
-\family default
-' provides additional detail).
-\end_layout
-
-\begin_layout Itemize
-Searching through modules and namespaces with `
-\family typewriter
-*
-\family default
-' wildcards, both when using the `
-\family typewriter
-?
-\family default
-' system and via the 
-\family typewriter
-%psearch
-\family default
- command.
-\end_layout
-
-\begin_layout Itemize
-Completion in the local namespace, by typing TAB at the prompt.
- This works for keywords, methods, variables and files in the current directory.
- This is supported via the readline library, and full access to configuring
- readline's behavior is provided.
-\end_layout
-
-\begin_layout Itemize
-Numbered input/output prompts with command history (persistent across sessions
- and tied to each profile), full searching in this history and caching of
- all input and output.
-\end_layout
-
-\begin_layout Itemize
-User-extensible `magic' commands.
- A set of commands prefixed with 
-\family typewriter
-%
-\family default
- is available for controlling IPython itself and provides directory control,
- namespace information and many aliases to common system shell commands.
-\end_layout
-
-\begin_layout Itemize
-Alias facility for defining your own system aliases.
-\end_layout
-
-\begin_layout Itemize
-Complete system shell access.
- Lines starting with ! are passed directly to the system shell, and using
- !! captures shell output into python variables for further use.
-\end_layout
-
-\begin_layout Itemize
-Background execution of Python commands in a separate thread.
- IPython has an internal job manager called 
-\family typewriter
-jobs
-\family default
-, and a conveninence backgrounding magic function called 
-\family typewriter
-%bg
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-The ability to expand python variables when calling the system shell.
- In a shell command, any python variable prefixed with 
-\family typewriter
-$
-\family default
- is expanded.
- A double 
-\family typewriter
-$$
-\family default
- allows passing a literal 
-\family typewriter
-$
-\family default
- to the shell (for access to shell and environment variables like 
-\family typewriter
-$PATH
-\family default
-).
-\end_layout
-
-\begin_layout Itemize
-Filesystem navigation, via a magic 
-\family typewriter
-%cd
-\family default
- command, along with a persistent bookmark system (using 
-\family typewriter
-%bookmark
-\family default
-) for fast access to frequently visited directories.
-\end_layout
-
-\begin_layout Itemize
-A lightweight persistence framework via the 
-\family typewriter
-%store
-\family default
- command, which allows you to save arbitrary Python variables.
- These get restored automatically when your session restarts.
-\end_layout
-
-\begin_layout Itemize
-Automatic indentation (optional) of code as you type (through the readline
- library).
-\end_layout
-
-\begin_layout Itemize
-Macro system for quickly re-executing multiple lines of previous input with
- a single name.
- Macros can be stored persistently via 
-\family typewriter
-%store
-\family default
- and edited via 
-\family typewriter
-%edit
-\family default
-.
- 
-\end_layout
-
-\begin_layout Itemize
-Session logging (you can then later use these logs as code in your programs).
- Logs can optionally timestamp all input, and also store session output
- (marked as comments, so the log remains valid Python source code).
-\end_layout
-
-\begin_layout Itemize
-Session restoring: logs can be replayed to restore a previous session to
- the state where you left it.
-\end_layout
-
-\begin_layout Itemize
-Verbose and colored exception traceback printouts.
- Easier to parse visually, and in verbose mode they produce a lot of useful
- debugging information (basically a terminal version of the cgitb module).
-\end_layout
-
-\begin_layout Itemize
-Auto-parentheses: callable objects can be executed without parentheses:
- 
-\family typewriter
-`sin 3'
-\family default
- is automatically converted to 
-\family typewriter
-`sin(3)
-\family default
-'.
-\end_layout
-
-\begin_layout Itemize
-Auto-quoting: using `
-\family typewriter
-,
-\family default
-' or `
-\family typewriter
-;
-\family default
-' as the first character forces auto-quoting of the rest of the line: 
-\family typewriter
-`,my_function a\InsetSpace ~
-b'
-\family default
- becomes automatically 
-\family typewriter
-`my_function("a","b")'
-\family default
-, while 
-\family typewriter
-`;my_function a\InsetSpace ~
-b'
-\family default
- becomes 
-\family typewriter
-`my_function("a b")'
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-Extensible input syntax.
- You can define filters that pre-process user input to simplify input in
- special situations.
- This allows for example pasting multi-line code fragments which start with
- 
-\family typewriter
-`>>>'
-\family default
- or 
-\family typewriter
-`...'
-\family default
- such as those from other python sessions or the standard Python documentation.
-\end_layout
-
-\begin_layout Itemize
-Flexible configuration system.
- It uses a configuration file which allows permanent setting of all command-line
- options, module loading, code and file execution.
- The system allows recursive file inclusion, so you can have a base file
- with defaults and layers which load other customizations for particular
- projects.
-\end_layout
-
-\begin_layout Itemize
-Embeddable.
- You can call IPython as a python shell inside your own python programs.
- This can be used both for debugging code or for providing interactive abilities
- to your programs with knowledge about the local namespaces (very useful
- in debugging and data analysis situations).
-\end_layout
-
-\begin_layout Itemize
-Easy debugger access.
- You can set IPython to call up an enhanced version of the Python debugger
- (
-\family typewriter
-pdb
-\family default
-) every time there is an uncaught exception.
- This drops you inside the code which triggered the exception with all the
- data live and it is possible to navigate the stack to rapidly isolate the
- source of a bug.
- The 
-\family typewriter
-%run
-\family default
- magic command --with the 
-\family typewriter
--d
-\family default
- option-- can run any script under 
-\family typewriter
-pdb
-\family default
-'s control, automatically setting initial breakpoints for you.
- This version of 
-\family typewriter
-pdb
-\family default
- has IPython-specific improvements, including tab-completion and traceback
- coloring support.
-\end_layout
-
-\begin_layout Itemize
-Profiler support.
- You can run single statements (similar to 
-\family typewriter
-profile.run()
-\family default
-) or complete programs under the profiler's control.
- While this is possible with standard 
-\family typewriter
-cProfile
-\family default
- or 
-\family typewriter
-profile
-\family default
- modules, IPython wraps this functionality with magic commands (see 
-\family typewriter
-`%prun'
-\family default
- and 
-\family typewriter
-`%run -p
-\family default
-') convenient for rapid interactive work.
-\end_layout
-
-\begin_layout Itemize
-Doctest support.
- The special 
-\family typewriter
-%doctest_mode
-\family default
- command toggles a mode that allows you to paste existing doctests (with
- leading `
-\family typewriter
->>>
-\family default
-' prompts and whitespace) and uses doctest-compatible prompts and output,
- so you can use IPython sessions as doctest code.
-\end_layout
-
-\begin_layout Subsection
-Portability and Python requirements
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Python requirements: 
-\series default
-IPython requires with Python version 2.3 or newer.
- If you are still using Python 2.2 and can not upgrade, the last version
- of IPython which worked with Python 2.2 was 0.6.15, so you will have to use
- that.
-\end_layout
-
-\begin_layout Standard
-IPython is developed under 
-\series bold
-Linux
-\series default
-, but it should work in any reasonable Unix-type system (tested OK under
- Solaris and the *BSD family, for which a port exists thanks to Dryice Liu).
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Mac OS X
-\series default
-: it works, apparently without any problems (thanks to Jim Boyle at Lawrence
- Livermore for the information).
- Thanks to Andrea Riciputi, Fink support is available.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-CygWin
-\series default
-: it works mostly OK, though some users have reported problems with prompt
- coloring.
- No satisfactory solution to this has been found so far, you may want to
- disable colors permanently in the 
-\family typewriter
-ipythonrc
-\family default
- configuration file if you experience problems.
- If you have proper color support under cygwin, please post to the IPython
- mailing list so this issue can be resolved for all users.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Windows
-\series default
-: it works well under Windows XP/2k, and I suspect NT should behave similarly.
- Section\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sub:Under-Windows}
-
-\end_inset
-
- describes installation details for Windows, including some additional tools
- needed on this platform.
-\end_layout
-
-\begin_layout Standard
-Windows 9x support is present, and has been reported to work fine (at least
- on WinME).
-\end_layout
-
-\begin_layout Standard
-Note, that I have very little access to and experience with Windows development.
- However, an excellent group of Win32 users (led by Ville Vainio), consistently
- contribute bugfixes and platform-specific enhancements, so they more than
- make up for my deficiencies on that front.
- In fact, Win32 users report using IPython as a system shell (see Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:IPython-as-shell}
-
-\end_inset
-
- for details), as it offers a level of control and features which the default
- 
-\family typewriter
-cmd.exe
-\family default
- doesn't provide.
-\end_layout
-
-\begin_layout Subsection
-Location
-\end_layout
-
-\begin_layout Standard
-IPython is generously hosted at 
-\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
-
-\end_inset
-
- by the Enthought, Inc and the SciPy project.
- This site offers downloads, subversion access, mailing lists and a bug
- tracking system.
- I am very grateful to Enthought (
-\begin_inset LatexCommand \htmlurl{http://www.enthought.com}
-
-\end_inset
-
-) and all of the SciPy team for their contribution.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:install}
-
-\end_inset
-
-Installation
-\end_layout
-
-\begin_layout Subsection
-Instant instructions
-\end_layout
-
-\begin_layout Standard
-If you are of the impatient kind, under Linux/Unix simply untar/unzip the
- download, then install with 
-\family typewriter
-`python setup.py install'
-\family default
-.
- Under Windows, double-click on the provided 
-\family typewriter
-.exe
-\family default
- binary installer.
-\end_layout
-
-\begin_layout Standard
-Then, take a look at Sections 
-\begin_inset LatexCommand \ref{sec:good_config}
-
-\end_inset
-
- for configuring things optimally and 
-\begin_inset LatexCommand \ref{sec:quick_tips}
-
-\end_inset
-
- for quick tips on efficient use of IPython.
- You can later refer to the rest of the manual for all the gory details.
-\end_layout
-
-\begin_layout Standard
-See the notes in sec.
- 
-\begin_inset LatexCommand \ref{sec:upgrade}
-
-\end_inset
-
- for upgrading IPython versions.
-\end_layout
-
-\begin_layout Subsection
-Detailed Unix instructions (Linux, Mac OS X, etc.)
-\end_layout
-
-\begin_layout Standard
-For RPM based systems, simply install the supplied package in the usual
- manner.
- If you download the tar archive, the process is:
-\end_layout
-
-\begin_layout Enumerate
-Unzip/untar the 
-\family typewriter
-ipython-XXX.tar.gz
-\family default
- file wherever you want (
-\family typewriter
-XXX
-\family default
- is the version number).
- It will make a directory called 
-\family typewriter
-ipython-XXX.
- 
-\family default
-Change into that directory where you will find the files 
-\family typewriter
-README
-\family default
- and 
-\family typewriter
-setup.py
-\family default
-.
-
-\family typewriter
- O
-\family default
-nce you've completed the installation, you can safely remove this directory.
- 
-\end_layout
-
-\begin_layout Enumerate
-If you are installing over a previous installation of version 0.2.0 or earlier,
- first remove your 
-\family typewriter
-$HOME/.ipython
-\family default
- directory, since the configuration file format has changed somewhat (the
- '=' were removed from all option specifications).
- Or you can call ipython with the 
-\family typewriter
--upgrade
-\family default
- option and it will do this automatically for you.
-\end_layout
-
-\begin_layout Enumerate
-IPython uses distutils, so you can install it by simply typing at the system
- prompt (don't type the 
-\family typewriter
-$
-\family default
-)
-\newline
-
-\family typewriter
-$ python setup.py install
-\family default
-
-\newline
-Note that this assumes you have root access to your machine.
- If you don't have root access or don't want IPython to go in the default
- python directories, you'll need to use the 
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|--home|
-\end_layout
-
-\end_inset
-
- option (or 
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|--prefix|
-\end_layout
-
-\end_inset
-
-).
- For example:
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|$ python setup.py install --home $HOME/local|
-\end_layout
-
-\end_inset
-
-
-\newline
-will install IPython into 
-\family typewriter
-$HOME/local 
-\family default
-and its subdirectories (creating them if necessary).
-\newline
-You can type
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|$ python setup.py --help|
-\end_layout
-
-\end_inset
-
- 
-\newline
-for more details.
-\newline
-Note that if you change the default location for 
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|--home|
-\end_layout
-
-\end_inset
-
- at installation, IPython may end up installed at a location which is not
- part of your 
-\family typewriter
-$PYTHONPATH
-\family default
- environment variable.
- In this case, you'll need to configure this variable to include the actual
- directory where the 
-\family typewriter
-IPython/
-\family default
- directory ended (typically the value you give to 
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|--home|
-\end_layout
-
-\end_inset
-
- plus 
-\family typewriter
-/lib/python
-\family default
-).
-\end_layout
-
-\begin_layout Subsubsection
-Mac OSX information
-\end_layout
-
-\begin_layout Standard
-Under OSX, there is a choice you need to make.
- Apple ships its own build of Python, which lives in the core OSX filesystem
- hierarchy.
- You can also manually install a separate Python, either purely by hand
- (typically in 
-\family typewriter
-/usr/local
-\family default
-) or by using Fink, which puts everything under 
-\family typewriter
-/sw
-\family default
-.
- Which route to follow is a matter of personal preference, as I've seen
- users who favor each of the approaches.
- Here I will simply list the known installation issues under OSX, along
- with their solutions.
-\end_layout
-
-\begin_layout Standard
-This page: 
-\begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html}
-
-\end_inset
-
- contains information on this topic, with additional details on how to make
- IPython and matplotlib play nicely under OSX.
-\end_layout
-
-\begin_layout Subsubsection*
-GUI problems
-\end_layout
-
-\begin_layout Standard
-The following instructions apply to an install of IPython under OSX from
- unpacking the 
-\family typewriter
-.tar.gz
-\family default
- distribution and installing it for the default Python interpreter shipped
- by Apple.
- If you are using a fink install, fink will take care of these details for
- you, by installing IPython against fink's Python.
-\end_layout
-
-\begin_layout Standard
-IPython offers various forms of support for interacting with graphical applicati
-ons from the command line, from simple Tk apps (which are in principle always
- supported by Python) to interactive control of WX, Qt and GTK apps.
- Under OSX, however, this requires that ipython is installed by calling
- the special 
-\family typewriter
-pythonw
-\family default
- script at installation time, which takes care of coordinating things with
- Apple's graphical environment.
-\end_layout
-
-\begin_layout Standard
-So when installing under OSX, it is best to use the following command:
-\family typewriter
-
-\newline
-
-\family default
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|  $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
-\end_layout
-
-\end_inset
-
-
-\newline
- or
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|  $ sudo pythonw setup.py install --install-scripts=/usr/bin|
-\end_layout
-
-\end_inset
-
-
-\newline
-depending on where you like to keep hand-installed executables.
-\end_layout
-
-\begin_layout Standard
-The resulting script will have an appropriate shebang line (the first line
- in the script whic begins with 
-\family typewriter
-#!...
-\family default
-) such that the ipython interpreter can interact with the OS X GUI.
- If the installed version does not work and has a shebang line that points
- to, for example, just 
-\family typewriter
-/usr/bin/python
-\family default
-, then you might have a stale, cached version in your 
-\family typewriter
-build/scripts-<python-version>
-\family default
- directory.
- Delete that directory and rerun the 
-\family typewriter
-setup.py
-\family default
-.
- 
-\end_layout
-
-\begin_layout Standard
-It is also a good idea to use the special flag 
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-verb|--install-scripts|
-\end_layout
-
-\end_inset
-
- as indicated above, to ensure that the ipython scripts end up in a location
- which is part of your 
-\family typewriter
-$PATH
-\family default
-.
- Otherwise Apple's Python will put the scripts in an internal directory
- not available by default at the command line (if you use 
-\family typewriter
-/usr/local/bin
-\family default
-, you need to make sure this is in your 
-\family typewriter
-$PATH
-\family default
-, which may not be true by default).
-\end_layout
-
-\begin_layout Subsubsection*
-Readline problems
-\end_layout
-
-\begin_layout Standard
-By default, the Python version shipped by Apple does 
-\emph on
-not
-\emph default
- include the readline library, so central to IPython's behavior.
- If you install IPython against Apple's Python, you will not have arrow
- keys, tab completion, etc.
- For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here:
-\newline
-
-\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip}
-
-\end_inset
-
- 
-\end_layout
-
-\begin_layout Standard
-If you are using OSX 10.4 (Tiger), after installing this package you need
- to either: 
-\end_layout
-
-\begin_layout Enumerate
-move 
-\family typewriter
-readline.so
-\family default
- from 
-\family typewriter
-/Library/Python/2.3
-\family default
- to 
-\family typewriter
-/Library/Python/2.3/site-packages
-\family default
-, or
-\end_layout
-
-\begin_layout Enumerate
-install 
-\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Users installing against Fink's Python or a properly hand-built one should
- not have this problem.
-\end_layout
-
-\begin_layout Subsubsection*
-DarwinPorts
-\end_layout
-
-\begin_layout Standard
-I report here a message from an OSX user, who suggests an alternative means
- of using IPython under this operating system with good results.
- Please let me know of any updates that may be useful for this section.
- His message is reproduced verbatim below:
-\end_layout
-
-\begin_layout Quote
-From: Markus Banfi 
-\family typewriter
-<markus.banfi-AT-mospheira.net>
-\end_layout
-
-\begin_layout Quote
-As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead
- of Fink.
- I had no problems installing ipython with DarwinPorts.
- It's just:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-sudo port install py-ipython
-\end_layout
-
-\begin_layout Quote
-It automatically resolved all dependencies (python24, readline, py-readline).
- So far I did not encounter any problems with the DarwinPorts port of ipython.
- 
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sub:Under-Windows}
-
-\end_inset
-
-Windows instructions
-\end_layout
-
-\begin_layout Standard
-Some of IPython's very useful features are:
-\end_layout
-
-\begin_layout Itemize
-Integrated readline support (Tab-based file, object and attribute completion,
- input history across sessions, editable command line, etc.)
-\end_layout
-
-\begin_layout Itemize
-Coloring of prompts, code and tracebacks.
-\end_layout
-
-\begin_layout Standard
-These, by default, are only available under Unix-like operating systems.
- However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit
- from them.
- His readline library originally implemented both GNU readline functionality
- and color support, so that IPython under Windows XP/2k can be as friendly
- and powerful as under Unix-like environments.
- 
-\end_layout
-
-\begin_layout Standard
-This library, now named 
-\family typewriter
-PyReadline
-\family default
-, has been absorbed by the IPython team (J�rgen Stenarson, in particular),
- and it continues to be developed with new features, as well as being distribute
-d directly from the IPython site.
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
- PyReadline
-\family default
- extension requires 
-\family typewriter
-CTypes
-\family default
- and the windows IPython installer needs 
-\family typewriter
-PyWin32
-\family default
-, so in all you need:
-\end_layout
-
-\begin_layout Enumerate
-
-\family typewriter
-PyWin32
-\family default
- from 
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/pywin32}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Enumerate
-
-\family typewriter
-PyReadline
-\family default
- for Windows from 
-\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org/moin/PyReadline/Intro}
-
-\end_inset
-
-.
- That page contains further details on using and configuring the system
- to your liking.
-\end_layout
-
-\begin_layout Enumerate
-Finally, 
-\emph on
-only 
-\emph default
-if you are using Python 2.3 or 2.4, you need 
-\family typewriter
-CTypes
-\family default
- from 
-\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes}
-
-\end_inset
-
- (you 
-\emph on
-must
-\emph default
- use version 0.9.1 or newer).
- This package is included in Python 2.5, so you don't need to manually get
- it if your Python version is 2.5 or newer.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Warning about a broken readline-like library:
-\series default
- several users have reported problems stemming from using the pseudo-readline
- library at 
-\begin_inset LatexCommand \htmlurl{http://newcenturycomputers.net/projects/readline.html}
-
-\end_inset
-
-.
- This is a broken library which, while called readline, only implements
- an incomplete subset of the readline API.
- Since it is still called readline, it fools IPython's detection mechanisms
- and causes unpredictable crashes later.
- If you wish to use IPython under Windows, you must NOT use this library,
- which for all purposes is (at least as of version 1.6) terminally broken.
-\end_layout
-
-\begin_layout Subsubsection
-Installation procedure
-\end_layout
-
-\begin_layout Standard
-Once you have the above installed, from the IPython download directory grab
- the 
-\family typewriter
-ipython-XXX.win32.exe
-\family default
- file, where 
-\family typewriter
-XXX
-\family default
- represents the version number.
- This is a regular windows executable installer, which you can simply double-cli
-ck to install.
- It will add an entry for IPython to your Start Menu, as well as registering
- IPython in the Windows list of applications, so you can later uninstall
- it from the Control Panel.
- 
-\end_layout
-
-\begin_layout Standard
-IPython tries to install the configuration information in a directory named
- 
-\family typewriter
-.ipython
-\family default
- (
-\family typewriter
-_ipython
-\family default
- under Windows) located in your `home' directory.
- IPython sets this directory by looking for a 
-\family typewriter
-HOME
-\family default
- environment variable; if such a variable does not exist, it uses 
-\family typewriter
-HOMEDRIVE
-\backslash
-HOMEPATH 
-\family default
-(these are always defined by Windows).
- This typically gives something like 
-\family typewriter
-C:
-\backslash
-Documents and Settings
-\backslash
-YourUserName
-\family default
-, but your local details may vary.
- In this directory you will find all the files that configure IPython's
- defaults, and you can put there your profiles and extensions.
- This directory is automatically added by IPython to 
-\family typewriter
-sys.path
-\family default
-, so anything you place there can be found by 
-\family typewriter
-import
-\family default
- statements.
-\end_layout
-
-\begin_layout Paragraph
-Upgrading
-\end_layout
-
-\begin_layout Standard
-For an IPython upgrade, you should first uninstall the previous version.
- This will ensure that all files and directories (such as the documentation)
- which carry embedded version strings in their names are properly removed.
-\end_layout
-
-\begin_layout Paragraph
-Manual installation under Win32
-\end_layout
-
-\begin_layout Standard
-In case the automatic installer does not work for some reason, you can download
- the 
-\family typewriter
-ipython-XXX.tar.gz
-\family default
- file, which contains the full IPython source distribution (the popular
- WinZip can read 
-\family typewriter
-.tar.gz
-\family default
- files).
- After uncompressing the archive, you can install it at a command terminal
- just like any other Python module, by using 
-\family typewriter
-`python setup.py install'
-\family default
-.
- 
-\end_layout
-
-\begin_layout Standard
-After the installation, run the supplied 
-\family typewriter
-win32_manual_post_install.py 
-\family default
-script, which creates the necessary Start Menu shortcuts for you.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:upgrade}
-
-\end_inset
-
-Upgrading from a previous version
-\end_layout
-
-\begin_layout Standard
-If you are upgrading from a previous version of IPython, after doing the
- routine installation described above, you should call IPython with the
- 
-\family typewriter
--upgrade
-\family default
- option the first time you run your new copy.
- This will automatically update your configuration directory while preserving
- copies of your old files.
- You can then later merge back any personal customizations you may have
- made into the new files.
- It is a good idea to do this as there may be new options available in the
- new configuration files which you will not have.
-\end_layout
-
-\begin_layout Standard
-Under Windows, if you don't know how to call python scripts with arguments
- from a command line, simply delete the old config directory and IPython
- will make a new one.
- Win2k and WinXP users will find it in 
-\family typewriter
-C:
-\backslash
-Documents and Settings
-\backslash
-YourUserName
-\backslash
-_ipython
-\family default
-, and Win 9x users under 
-\family typewriter
-C:
-\backslash
-Program Files
-\backslash
-IPython
-\backslash
-_ipython.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:good_config}
-
-\end_inset
-
-
-\begin_inset OptArg
-status collapsed
-
-\begin_layout Standard
-Initial configuration
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-ldots
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-Initial configuration of your environment
-\end_layout
-
-\begin_layout Standard
-This section will help you set various things in your environment for your
- IPython sessions to be as efficient as possible.
- All of IPython's configuration information, along with several example
- files, is stored in a directory named by default 
-\family typewriter
-$HOME/.ipython
-\family default
-.
- You can change this by defining the environment variable 
-\family typewriter
-IPYTHONDIR
-\family default
-, or at runtime with the command line option 
-\family typewriter
--ipythondir
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-If all goes well, the first time you run IPython it should automatically
- create a user copy of the config directory for you, based on its builtin
- defaults.
- You can look at the files it creates to learn more about configuring the
- system.
- The main file you will modify to configure IPython's behavior is called
- 
-\family typewriter
-ipythonrc
-\family default
- (with a 
-\family typewriter
-.ini
-\family default
- extension under Windows), included for reference in Sec.
- 
-\begin_inset LatexCommand \ref{sec:ipytonrc-sample}
-
-\end_inset
-
-.
- This file is very commented and has many variables you can change to suit
- your taste, you can find more details in Sec.
- 
-\begin_inset LatexCommand \ref{sec:customization}
-
-\end_inset
-
-.
- Here we discuss the basic things you will want to make sure things are
- working properly from the beginning.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:help-access}
-
-\end_inset
-
-Access to the Python help system
-\end_layout
-
-\begin_layout Standard
-This is true for Python in general (not just for IPython): you should have
- an environment variable called 
-\family typewriter
-PYTHONDOCS
-\family default
- pointing to the directory where your HTML Python documentation lives.
- In my system it's 
-\family typewriter
-/usr/share/doc/python-docs-2.3.4/html
-\family default
-, check your local details or ask your systems administrator.
- 
-\end_layout
-
-\begin_layout Standard
-This is the directory which holds the HTML version of the Python manuals.
- Unfortunately it seems that different Linux distributions package these
- files differently, so you may have to look around a bit.
- Below I show the contents of this directory on my system for reference:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-[html]> ls
-\newline
-about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat
- tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
-\end_layout
-
-\begin_layout Standard
-You should really make sure this variable is correctly set so that Python's
- pydoc-based help system works.
- It is a powerful and convenient system with full access to the Python manuals
- and all modules accessible to you.
-\end_layout
-
-\begin_layout Standard
-Under Windows it seems that pydoc finds the documentation automatically,
- so no extra setup appears necessary.
-\end_layout
-
-\begin_layout Subsection
-Editor
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%edit
-\family default
- command (and its alias 
-\family typewriter
-%ed
-\family default
-) will invoke the editor set in your environment as 
-\family typewriter
-EDITOR
-\family default
-.
- If this variable is not set, it will default to 
-\family typewriter
-vi
-\family default
- under Linux/Unix and to 
-\family typewriter
-notepad
-\family default
- under Windows.
- You may want to set this variable properly and to a lightweight editor
- which doesn't take too long to start (that is, something other than a new
- instance of 
-\family typewriter
-Emacs
-\family default
-).
- This way you can edit multi-line code quickly and with the power of a real
- editor right inside IPython.
- 
-\end_layout
-
-\begin_layout Standard
-If you are a dedicated 
-\family typewriter
-Emacs
-\family default
- user, you should set up the 
-\family typewriter
-Emacs
-\family default
- server so that new requests are handled by the original process.
- This means that almost no time is spent in handling the request (assuming
- an 
-\family typewriter
-Emacs
-\family default
- process is already running).
- For this to work, you need to set your 
-\family typewriter
-EDITOR 
-\family default
-environment variable to 
-\family typewriter
-'emacsclient'
-\family default
-.
-
-\family typewriter
- 
-\family default
-The code below, supplied by Francois Pinard, can then be used in your 
-\family typewriter
-.emacs
-\family default
- file to enable the server:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-(defvar server-buffer-clients)
-\newline
-(when (and (fboundp 'server-start) (string-equal
- (getenv "TERM") 'xterm))
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-(server-start)
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-(defun fp-kill-server-with-buffer-routine ()
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-(and server-buffer-clients (server-done)))
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
-\end_layout
-
-\begin_layout Standard
-You can also set the value of this editor via the commmand-line option '-
-\family typewriter
-editor'
-\family default
- or in your 
-\family typewriter
-ipythonrc
-\family default
- file.
- This is useful if you wish to use specifically for IPython an editor different
- from your typical default (and for Windows users who tend to use fewer
- environment variables).
-\end_layout
-
-\begin_layout Subsection
-Color 
-\end_layout
-
-\begin_layout Standard
-The default IPython configuration has most bells and whistles turned on
- (they're pretty safe).
- But there's one that 
-\emph on
-may
-\emph default
- cause problems on some systems: the use of color on screen for displaying
- information.
- This is very useful, since IPython can show prompts and exception tracebacks
- with various colors, display syntax-highlighted source code, and in general
- make it easier to visually parse information.
-\end_layout
-
-\begin_layout Standard
-The following terminals seem to handle the color sequences fine:
-\end_layout
-
-\begin_layout Itemize
-Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm.
-\end_layout
-
-\begin_layout Itemize
-CDE terminal (tested under Solaris).
- This one boldfaces light colors.
-\end_layout
-
-\begin_layout Itemize
-(X)Emacs buffers.
- See sec.
-\begin_inset LatexCommand \ref{sec:emacs}
-
-\end_inset
-
- for more details on using IPython with (X)Emacs.
-\end_layout
-
-\begin_layout Itemize
-A Windows (XP/2k) command prompt 
-\emph on
-with Gary Bishop's support extensions
-\emph default
-.
- Gary's extensions are discussed in Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sub:Under-Windows}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Itemize
-A Windows (XP/2k) CygWin shell.
- Although some users have reported problems; it is not clear whether there
- is an issue for everyone or only under specific configurations.
- If you have full color support under cygwin, please post to the IPython
- mailing list so this issue can be resolved for all users.
-\end_layout
-
-\begin_layout Standard
-These have shown problems:
-\end_layout
-
-\begin_layout Itemize
-Windows command prompt in WinXP/2k logged into a Linux machine via telnet
- or ssh.
-\end_layout
-
-\begin_layout Itemize
-Windows native command prompt in WinXP/2k, 
-\emph on
-without 
-\emph default
-Gary Bishop's extensions.
- Once Gary's readline library is installed, the normal WinXP/2k command
- prompt works perfectly.
-\end_layout
-
-\begin_layout Standard
-Currently the following color schemes are available:
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-NoColor
-\family default
-: uses no color escapes at all (all escapes are empty 
-\begin_inset Quotes eld
-\end_inset
-
- 
-\begin_inset Quotes eld
-\end_inset
-
- strings).
- This 'scheme' is thus fully safe to use in any terminal.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-Linux
-\family default
-: works well in Linux console type environments: dark background with light
- fonts.
- It uses bright colors for information, so it is difficult to read if you
- have a light colored background.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-LightBG
-\family default
-: the basic colors are similar to those in the 
-\family typewriter
-Linux
-\family default
- scheme but darker.
- It is easy to read in terminals with light backgrounds.
-\end_layout
-
-\begin_layout Standard
-IPython uses colors for two main groups of things: prompts and tracebacks
- which are directly printed to the terminal, and the object introspection
- system which passes large sets of data through a pager.
-\end_layout
-
-\begin_layout Subsubsection
-Input/Output prompts and exception tracebacks
-\end_layout
-
-\begin_layout Standard
-You can test whether the colored prompts and tracebacks work on your system
- interactively by typing 
-\family typewriter
-'%colors Linux'
-\family default
- at the prompt (use '
-\family typewriter
-%colors LightBG'
-\family default
- if your terminal has a light background).
- If the input prompt shows garbage like:
-\newline
-
-\family typewriter
-[0;32mIn [[1;32m1[0;32m]: [0;00m
-\family default
-
-\newline
-instead of (in color) something like:
-\newline
-
-\family typewriter
-In [1]:
-\family default
- 
-\newline
-this means that your terminal doesn't properly handle color escape sequences.
- You can go to a 'no color' mode by typing '
-\family typewriter
-%colors NoColor
-\family default
-'.
- 
-\end_layout
-
-\begin_layout Standard
-You can try using a different terminal emulator program (Emacs users, see
- below).
- To permanently set your color preferences, edit the file
-\family typewriter
- $HOME/.ipython/ipythonrc 
-\family default
-and set the 
-\family typewriter
-colors
-\family default
- option to the desired value.
-\end_layout
-
-\begin_layout Subsubsection
-Object details (types, docstrings, source code, etc.)
-\end_layout
-
-\begin_layout Standard
-IPython has a set of special functions for studying the objects you are
- working with, discussed in detail in Sec.
- 
-\begin_inset LatexCommand \ref{sec:dyn-object-info}
-
-\end_inset
-
-.
- But this system relies on passing information which is longer than your
- screen through a data pager, such as the common Unix 
-\family typewriter
-less
-\family default
- and 
-\family typewriter
-more
-\family default
- programs.
- In order to be able to see this information in color, your pager needs
- to be properly configured.
- I strongly recommend using 
-\family typewriter
-less
-\family default
- instead of 
-\family typewriter
-more
-\family default
-, as it seems that 
-\family typewriter
-more
-\family default
- simply can not understand colored text correctly.
-\end_layout
-
-\begin_layout Standard
-In order to configure 
-\family typewriter
-less
-\family default
- as your default pager, do the following:
-\end_layout
-
-\begin_layout Enumerate
-Set the environment 
-\family typewriter
-PAGER
-\family default
- variable to 
-\family typewriter
-less
-\family default
-.
-\end_layout
-
-\begin_layout Enumerate
-Set the environment 
-\family typewriter
-LESS
-\family default
- variable to 
-\family typewriter
--r
-\family default
- (plus any other options you always want to pass to 
-\family typewriter
-less
-\family default
- by default).
- This tells 
-\family typewriter
-less
-\family default
- to properly interpret control sequences, which is how color information
- is given to your terminal.
-\end_layout
-
-\begin_layout Standard
-For the 
-\family typewriter
-csh
-\family default
- or 
-\family typewriter
-tcsh
-\family default
- shells, add to your 
-\family typewriter
-~/.cshrc
-\family default
- file the lines:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-setenv PAGER less
-\newline
-setenv LESS -r
-\end_layout
-
-\begin_layout Standard
-There is similar syntax for other Unix shells, look at your system documentation
- for details.
-\end_layout
-
-\begin_layout Standard
-If you are on a system which lacks proper data pagers (such as Windows),
- IPython will use a very limited builtin pager.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:emacs}
-
-\end_inset
-
-(X)Emacs configuration
-\end_layout
-
-\begin_layout Standard
-Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently
- (X)Emacs and IPython get along very well.
- 
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Important note:
-\series default
- You will need to use a recent enough version of 
-\family typewriter
-python-mode.el
-\family default
-, along with the file 
-\family typewriter
-ipython.el
-\family default
-.
- You can check that the version you have of 
-\family typewriter
-python-mode.el
-\family default
- is new enough by either looking at the revision number in the file itself,
- or asking for it in (X)Emacs via 
-\family typewriter
-M-x py-version
-\family default
-.
- Versions 4.68 and newer contain the necessary fixes for proper IPython support.
-\end_layout
-
-\begin_layout Standard
-The file 
-\family typewriter
-ipython.el
-\family default
- is included with the IPython distribution, in the documentation directory
- (where this manual resides in PDF and HTML formats).
-\end_layout
-
-\begin_layout Standard
-Once you put these files in your Emacs path, all you need in your 
-\family typewriter
-.emacs
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-(require 'ipython)
-\end_layout
-
-\begin_layout Standard
-This should give you full support for executing code snippets via IPython,
- opening IPython as your Python shell via 
-\family typewriter
-C-c\InsetSpace ~
-!
-\family default
-, etc.
- 
-\end_layout
-
-\begin_layout Standard
-If you happen to get garbage instead of colored prompts as described in
- the previous section, you may need to set also in your 
-\family typewriter
-.emacs
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-(setq ansi-color-for-comint-mode t)
-\end_layout
-
-\begin_layout Subsubsection*
-Notes
-\end_layout
-
-\begin_layout Itemize
-There is one caveat you should be aware of: you must start the IPython shell
- 
-\emph on
-before
-\emph default
- attempting to execute any code regions via 
-\family typewriter
-C-c\InsetSpace ~
-|
-\family default
-.
- Simply type 
-\family typewriter
-C-c\InsetSpace ~
-!
-\family default
- to start IPython before passing any code regions to the interpreter, and
- you shouldn't experience any problems.
-\newline
-This is due to a bug in Python itself,
- which has been fixed for Python 2.3, but exists as of Python 2.2.2 (reported
- as SF bug [ 737947 ]).
-\end_layout
-
-\begin_layout Itemize
-The (X)Emacs support is maintained by Alexander Schmolck, so all comments/reques
-ts should be directed to him through the IPython mailing lists.
- 
-\end_layout
-
-\begin_layout Itemize
-This code is still somewhat experimental so it's a bit rough around the
- edges (although in practice, it works quite well).
-\end_layout
-
-\begin_layout Itemize
-Be aware that if you customize 
-\family typewriter
-py-python-command
-\family default
- previously, this value will override what 
-\family typewriter
-ipython.el
-\family default
- does (because loading the customization variables comes later).
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:quick_tips}
-
-\end_inset
-
-Quick tips
-\end_layout
-
-\begin_layout Standard
-IPython can be used as an improved replacement for the Python prompt, and
- for that you don't really need to read any more of this manual.
- But in this section we'll try to summarize a few tips on how to make the
- most effective use of it for everyday Python development, highlighting
- things you might miss in the rest of the manual (which is getting long).
- We'll give references to parts in the manual which provide more detail
- when appropriate.
-\end_layout
-
-\begin_layout Standard
-The following article by Jeremy Jones provides an introductory tutorial
- about IPython:
-\newline
-
-\begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Itemize
-The TAB key.
- TAB-completion, especially for attributes, is a convenient way to explore
- the structure of any object you're dealing with.
- Simply type 
-\family typewriter
-object_name.<TAB>
-\family default
- and a list of the object's attributes will be printed (see sec.
- 
-\begin_inset LatexCommand \ref{sec:readline}
-
-\end_inset
-
- for more).
- Tab completion also works on file and directory names, which combined with
- IPython's alias system allows you to do from within IPython many of the
- things you normally would need the system shell for.
- 
-\end_layout
-
-\begin_layout Itemize
-Explore your objects.
- Typing 
-\family typewriter
-object_name?
-\family default
- will print all sorts of details about any object, including docstrings,
- function definition lines (for call arguments) and constructor details
- for classes.
- The magic commands 
-\family typewriter
-%pdoc
-\family default
-, 
-\family typewriter
-%pdef
-\family default
-, 
-\family typewriter
-%psource
-\family default
- and 
-\family typewriter
-%pfile
-\family default
- will respectively print the docstring, function definition line, full source
- code and the complete file for any object (when they can be found).
- If automagic is on (it is by default), you don't need to type the '
-\family typewriter
-%
-\family default
-' explicitly.
- See sec.
- 
-\begin_inset LatexCommand \ref{sec:dyn-object-info}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-The 
-\family typewriter
-%run
-\family default
- magic command allows you to run any python script and load all of its data
- directly into the interactive namespace.
- Since the file is re-read from disk each time, changes you make to it are
- reflected immediately (in contrast to the behavior of 
-\family typewriter
-import
-\family default
-).
- I rarely use 
-\family typewriter
-import
-\family default
- for code I am testing, relying on 
-\family typewriter
-%run
-\family default
- instead.
- See sec.
- 
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
- for more on this and other magic commands, or type the name of any magic
- command and ? to get details on it.
- See also sec.
- 
-\begin_inset LatexCommand \ref{sec:dreload}
-
-\end_inset
-
- for a recursive reload command.
-\newline
-
-\family typewriter
-%run
-\family default
- also has special flags for timing the execution of your scripts (
-\family typewriter
--t
-\family default
-) and for executing them under the control of either Python's 
-\family typewriter
-pdb 
-\family default
-debugger (
-\family typewriter
--d
-\family default
-) or profiler (
-\family typewriter
--p
-\family default
-).
- With all of these, 
-\family typewriter
-%run
-\family default
- can be used as the main tool for efficient interactive development of code
- which you write in your editor of choice.
-\end_layout
-
-\begin_layout Itemize
-Use the Python debugger, 
-\family typewriter
-pdb
-\family default
-
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-Thanks to Christian Hart and Matthew Arnison for the suggestions leading
- to IPython's improved debugger and profiler support.
-\end_layout
-
-\end_inset
-
-.
- The 
-\family typewriter
-%pdb
-\family default
- command allows you to toggle on and off the automatic invocation of an
- IPython-enhanced 
-\family typewriter
-pdb
-\family default
- debugger (with coloring, tab completion and more) at any uncaught exception.
- The advantage of this is that 
-\family typewriter
-pdb
-\family default
- starts 
-\emph on
-inside
-\emph default
- the function where the exception occurred, with all data still available.
- You can print variables, see code, execute statements and even walk up
- and down the call stack to track down the true source of the problem (which
- often is many layers in the stack above where the exception gets triggered).
-\newline
-Runn
-ing programs with 
-\family typewriter
-%run
-\family default
- and pdb active can be an efficient to develop and debug code, in many cases
- eliminating the need for 
-\family typewriter
-print
-\family default
- statements or external debugging tools.
- I often simply put a 
-\family typewriter
-1/0
-\family default
- in a place where I want to take a look so that pdb gets called, quickly
- view whatever variables I need to or test various pieces of code and then
- remove the 
-\family typewriter
-1/0
-\family default
-.
-\newline
-Note also that `
-\family typewriter
-%run -d
-\family default
-' activates 
-\family typewriter
-pdb
-\family default
- and automatically sets initial breakpoints for you to step through your
- code, watch variables, etc.
- See Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:cache_output}
-
-\end_inset
-
- for details.
-\end_layout
-
-\begin_layout Itemize
-Use the output cache.
- All output results are automatically stored in a global dictionary named
- 
-\family typewriter
-Out
-\family default
- and variables named 
-\family typewriter
-_1
-\family default
-, 
-\family typewriter
-_2
-\family default
-, etc.
- alias them.
- For example, the result of input line 4 is available either as 
-\family typewriter
-Out[4]
-\family default
- or as 
-\family typewriter
-_4
-\family default
-.
- Additionally, three variables named 
-\family typewriter
-_
-\family default
-, 
-\family typewriter
-__
-\family default
- and 
-\family typewriter
-___
-\family default
- are always kept updated with the for the last three results.
- This allows you to recall any previous result and further use it for new
- calculations.
- See Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:cache_output}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Put a '
-\family typewriter
-;
-\family default
-' at the end of a line to supress the printing of output.
- This is useful when doing calculations which generate long output you are
- not interested in seeing.
- The 
-\family typewriter
-_*
-\family default
- variables and the 
-\family typewriter
-Out[]
-\family default
- list do get updated with the contents of the output, even if it is not
- printed.
- You can thus still access the generated results this way for further processing.
-\end_layout
-
-\begin_layout Itemize
-A similar system exists for caching input.
- All input is stored in a global list called 
-\family typewriter
-In
-\family default
- , so you can re-execute lines 22 through 28 plus line 34 by typing 
-\family typewriter
-'exec In[22:29]+In[34]'
-\family default
- (using Python slicing notation).
- If you need to execute the same set of lines often, you can assign them
- to a macro with the 
-\family typewriter
-%macro
-\family default
- 
-\family typewriter
-function.
- 
-\family default
-See sec.
- 
-\begin_inset LatexCommand \ref{sec:cache_input}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Use your input history.
- The 
-\family typewriter
-%hist
-\family default
- command can show you all previous input, without line numbers if desired
- (option 
-\family typewriter
--n
-\family default
-) so you can directly copy and paste code either back in IPython or in a
- text editor.
- You can also save all your history by turning on logging via 
-\family typewriter
-%logstart
-\family default
-; these logs can later be either reloaded as IPython sessions or used as
- code for your programs.
-\end_layout
-
-\begin_layout Itemize
-Define your own system aliases.
- Even though IPython gives you access to your system shell via the 
-\family typewriter
-!
-\family default
- prefix, it is convenient to have aliases to the system commands you use
- most often.
- This allows you to work seamlessly from inside IPython with the same commands
- you are used to in your system shell.
-\newline
-IPython comes with some pre-defined
- aliases and a complete system for changing directories, both via a stack
- (see 
-\family typewriter
-%pushd
-\family default
-, 
-\family typewriter
-%popd
-\family default
- and 
-\family typewriter
-%dhist
-\family default
-) and via direct 
-\family typewriter
-%cd
-\family default
-.
- The latter keeps a history of visited directories and allows you to go
- to any previously visited one.
-\end_layout
-
-\begin_layout Itemize
-Use Python to manipulate the results of system commands.
- The `
-\family typewriter
-!!
-\family default
-' special syntax, and the 
-\family typewriter
-%sc
-\family default
- and 
-\family typewriter
-%sx
-\family default
- magic commands allow you to capture system output into Python variables.
-\end_layout
-
-\begin_layout Itemize
-Expand python variables when calling the shell (either via 
-\family typewriter
-`!'
-\family default
- and 
-\family typewriter
-`!!'
-\family default
- or via aliases) by prepending a 
-\family typewriter
-$
-\family default
- in front of them.
- You can also expand complete python expressions.
- See sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sub:System-shell-access}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Use profiles to maintain different configurations (modules to load, function
- definitions, option settings) for particular tasks.
- You can then have customized versions of IPython for specific purposes.
- See sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:profiles}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Embed IPython in your programs.
- A few lines of code are enough to load a complete IPython inside your own
- programs, giving you the ability to work with your data interactively after
- automatic processing has been completed.
- See sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:embed}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Use the Python profiler.
- When dealing with performance issues, the 
-\family typewriter
-%run
-\family default
- command with a 
-\family typewriter
--p
-\family default
- option allows you to run complete programs under the control of the Python
- profiler.
- The 
-\family typewriter
-%prun
-\family default
- command does a similar job for single Python expressions (like function
- calls).
-\end_layout
-
-\begin_layout Itemize
-Use the IPython.demo.Demo class to load any Python script as an interactive
- demo.
- With a minimal amount of simple markup, you can control the execution of
- the script, stopping as needed.
- See sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:interactive-demos}
-
-\end_inset
-
- for more.
-\end_layout
-
-\begin_layout Itemize
-Run your doctests from within IPython for development and debugging.
- The special 
-\family typewriter
-%doctest_mode
-\family default
- command toggles a mode where the prompt, output and exceptions display
- matches as closely as possible that of the default Python interpreter.
- In addition, this mode allows you to directly paste in code that contains
- leading `
-\family typewriter
->>>
-\family default
-' prompts, even if they have extra leading whitespace (as is common in doctest
- files).
- This combined with the `
-\family typewriter
-%history -t
-\family default
-n' call to see your translated history (with these extra prompts removed
- and no line numbers) allows for an easy doctest workflow, where you can
- go from doctest to interactive execution to pasting into valid Python code
- as needed.
-\end_layout
-
-\begin_layout Subsection
-Source code handling tips
-\end_layout
-
-\begin_layout Standard
-IPython is a line-oriented program, without full control of the terminal.
- Therefore, it doesn't support true multiline editing.
- However, it has a number of useful tools to help you in dealing effectively
- with more complex editing.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%edit
-\family default
- command gives a reasonable approximation of multiline editing, by invoking
- your favorite editor on the spot.
- IPython will execute the code you type in there as if it were typed interactive
-ly.
- Type 
-\family typewriter
-%edit?
-\family default
- for the full details on the edit command.
-\end_layout
-
-\begin_layout Standard
-If you have typed various commands during a session, which you'd like to
- reuse, IPython provides you with a number of tools.
- Start by using 
-\family typewriter
-%hist
-\family default
- to see your input history, so you can see the line numbers of all input.
- Let us say that you'd like to reuse lines 10 through 20, plus lines 24
- and 28.
- All the commands below can operate on these with the syntax
-\end_layout
-
-\begin_layout LyX-Code
-%command 10-20 24 28
-\end_layout
-
-\begin_layout Standard
-where the command given can be:
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%macro <macroname>
-\family default
-: this stores the lines into a variable which, when called at the prompt,
- re-executes the input.
- Macros can be edited later using 
-\family typewriter
-`%edit macroname
-\family default
-', and they can be stored persistently across sessions with `
-\family typewriter
-%store macroname
-\family default
-' (the storage system is per-profile).
- The combination of quick macros, persistent storage and editing, allows
- you to easily refine quick-and-dirty interactive input into permanent utilities
-, always available both in IPython and as files for general reuse.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%edit
-\family default
-: this will open a text editor with those lines pre-loaded for further modificat
-ion.
- It will then execute the resulting file's contents as if you had typed
- it at the prompt.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%save <filename>
-\family default
-: this saves the lines directly to a named file on disk.
-\end_layout
-
-\begin_layout Standard
-While 
-\family typewriter
-%macro
-\family default
- saves input lines into memory for interactive re-execution, sometimes you'd
- like to save your input directly to a file.
- The 
-\family typewriter
-%save
-\family default
- magic does this: its input sytnax is the same as 
-\family typewriter
-%macro
-\family default
-, but it saves your input directly to a Python file.
- Note that the 
-\family typewriter
-%logstart
-\family default
- command also saves input, but it logs 
-\emph on
-all
-\emph default
- input to disk (though you can temporarily suspend it and reactivate it
- with 
-\family typewriter
-%logoff/%logon
-\family default
-); 
-\family typewriter
-%save
-\family default
- allows you to select which lines of input you need to save.
-\end_layout
-
-\begin_layout Subsubsection*
-Lightweight 'version control'
-\end_layout
-
-\begin_layout Standard
-When you call 
-\family typewriter
-%edit
-\family default
- with no arguments, IPython opens an empty editor with a temporary file,
- and it returns the contents of your editing session as a string variable.
- Thanks to IPython's output caching mechanism, this is automatically stored:
-\end_layout
-
-\begin_layout LyX-Code
-In [1]: %edit
-\end_layout
-
-\begin_layout LyX-Code
-IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
-\end_layout
-
-\begin_layout LyX-Code
-Editing...
- done.
- Executing edited code...
-\end_layout
-
-\begin_layout LyX-Code
-hello - this is a temporary file
-\end_layout
-
-\begin_layout LyX-Code
-Out[1]: "print 'hello - this is a temporary file'
-\backslash
-n"
-\end_layout
-
-\begin_layout Standard
-Now, if you call 
-\family typewriter
-`%edit -p'
-\family default
-, IPython tries to open an editor with the same data as the last time you
- used 
-\family typewriter
-%edit
-\family default
-.
- So if you haven't used 
-\family typewriter
-%edit
-\family default
- in the meantime, this same contents will reopen; however, it will be done
- in a 
-\emph on
-new file
-\emph default
-.
- This means that if you make changes and you later want to find an old version,
- you can always retrieve it by using its output number, via 
-\family typewriter
-`%edit _NN'
-\family default
-, where 
-\family typewriter
-NN
-\family default
- is the number of the output prompt.
-\end_layout
-
-\begin_layout Standard
-Continuing with the example above, this should illustrate this idea:
-\end_layout
-
-\begin_layout LyX-Code
-In [2]: edit -p
-\end_layout
-
-\begin_layout LyX-Code
-IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
-\end_layout
-
-\begin_layout LyX-Code
-Editing...
- done.
- Executing edited code...
-\end_layout
-
-\begin_layout LyX-Code
-hello - now I made some changes
-\end_layout
-
-\begin_layout LyX-Code
-Out[2]: "print 'hello - now I made some changes'
-\backslash
-n"
-\end_layout
-
-\begin_layout LyX-Code
-In [3]: edit _1
-\end_layout
-
-\begin_layout LyX-Code
-IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
-\end_layout
-
-\begin_layout LyX-Code
-Editing...
- done.
- Executing edited code...
-\end_layout
-
-\begin_layout LyX-Code
-hello - this is a temporary file
-\end_layout
-
-\begin_layout LyX-Code
-IPython version control at work :)
-\end_layout
-
-\begin_layout LyX-Code
-Out[3]: "print 'hello - this is a temporary file'
-\backslash
-nprint 'IPython version control at work :)'
-\backslash
-n"
-\end_layout
-
-\begin_layout Standard
-This section was written after a contribution by Alexander Belchenko on
- the IPython user list.
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Subsection
-Effective logging
-\end_layout
-
-\begin_layout Standard
-A very useful suggestion sent in by Robert Kern follows:
-\end_layout
-
-\begin_layout Standard
-I recently happened on a nifty way to keep tidy per-project log files.
- I made a profile for my project (which is called "parkfield").
-\end_layout
-
-\begin_layout LyX-Code
-include ipythonrc
-\end_layout
-
-\begin_layout LyX-Code
-# cancel earlier logfile invocation:
-\end_layout
-
-\begin_layout LyX-Code
-logfile ''
-\end_layout
-
-\begin_layout LyX-Code
-execute import time
-\end_layout
-
-\begin_layout LyX-Code
-execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
-\end_layout
-
-\begin_layout LyX-Code
-execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
-\end_layout
-
-\begin_layout Standard
-I also added a shell alias for convenience:
-\end_layout
-
-\begin_layout LyX-Code
-alias parkfield="ipython -pylab -profile parkfield"
-\end_layout
-
-\begin_layout Standard
-Now I have a nice little directory with everything I ever type in, organized
- by project and date.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Contribute your own: 
-\series default
-If you have your own favorite tip on using IPython efficiently for a certain
- task (especially things which can't be done in the normal Python interpreter),
- don't hesitate to send it!
-\end_layout
-
-\begin_layout Section
-Command-line use
-\end_layout
-
-\begin_layout Standard
-You start IPython with the command:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-$ ipython [options] files
-\end_layout
-
-\begin_layout Standard
-If invoked with no options, it executes all the files listed in sequence
- and drops you into the interpreter while still acknowledging any options
- you may have set in your ipythonrc file.
- This behavior is different from standard Python, which when called as 
-\family typewriter
-python -i
-\family default
- will only execute one file and ignore your configuration setup.
-\end_layout
-
-\begin_layout Standard
-Please note that some of the configuration options are not available at
- the command line, simply because they are not practical here.
- Look into your ipythonrc configuration file for details on those.
- This file typically installed in the 
-\family typewriter
-$HOME/.ipython
-\family default
- directory.
- For Windows users, 
-\family typewriter
-$HOME
-\family default
- resolves to 
-\family typewriter
-C:
-\backslash
-
-\backslash
-Documents and Settings
-\backslash
-
-\backslash
-YourUserName
-\family default
- in most instances.
- In the rest of this text, we will refer to this directory as 
-\family typewriter
-IPYTHONDIR
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:threading-opts}
-
-\end_inset
-
-Special Threading Options
-\end_layout
-
-\begin_layout Standard
-The following special options are ONLY valid at the beginning of the command
- line, and not later.
- This is because they control the initial- ization of ipython itself, before
- the normal option-handling mechanism is active.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--gthread,\InsetSpace ~
--qthread,\InsetSpace ~
--q4thread,\InsetSpace ~
--wthread,\InsetSpace ~
--pylab:
-\family default
-\series default
- Only 
-\emph on
-one
-\emph default
- of these can be given, and it can only be given as the first option passed
- to IPython (it will have no effect in any other position).
- They provide threading support for the GTK, Qt (versions 3 and 4) and WXPython
- toolkits, and for the matplotlib library.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- With any of the first four options, IPython starts running a separate thread
- for the graphical toolkit's operation, so that you can open and control
- graphical elements from within an IPython command line, without blocking.
- All four provide essentially the same functionality, respectively for GTK,
- Qt3, Qt4 and WXWidgets (via their Python interfaces).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Note that with 
-\family typewriter
--wthread
-\family default
-, you can additionally use the -wxversion option to request a specific version
- of wx to be used.
- This requires that you have the 
-\family typewriter
-wxversion
-\family default
- Python module installed, which is part of recent wxPython distributions.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- If 
-\family typewriter
--pylab
-\family default
- is given, IPython loads special support for the mat plotlib library (
-\begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}
-
-\end_inset
-
-), allowing interactive usage of any of its backends as defined in the user's
- 
-\family typewriter
-~/.matplotlib/matplotlibrc
-\family default
- file.
- It automatically activates GTK, Qt or WX threading for IPyhton if the choice
- of matplotlib backend requires it.
- It also modifies the 
-\family typewriter
-%run
-\family default
- command to correctly execute (without blocking) any matplotlib-based script
- which calls 
-\family typewriter
-show()
-\family default
- at the end.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--tk
-\family default
-\series default
- The 
-\family typewriter
--g/q/q4/wthread
-\family default
- options, and 
-\family typewriter
--pylab
-\family default
- (if matplotlib is configured to use GTK, Qt3, Qt4 or WX), will normally
- block Tk graphical interfaces.
- This means that when either GTK, Qt or WX threading is active, any attempt
- to open a Tk GUI will result in a dead window, and possibly cause the Python
- interpreter to crash.
- An extra option, 
-\family typewriter
--tk
-\family default
-, is available to address this issue.
- It can 
-\emph on
-only
-\emph default
- be given as a 
-\emph on
-second
-\emph default
- option after any of the above (
-\family typewriter
--gthread
-\family default
-, 
-\family typewriter
--wthread
-\family default
- or 
-\family typewriter
--pylab
-\family default
-).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- If 
-\family typewriter
--tk
-\family default
- is given, IPython will try to coordinate Tk threading with GTK, Qt or WX.
- This is however potentially unreliable, and you will have to test on your
- platform and Python configuration to determine whether it works for you.
- Debian users have reported success, apparently due to the fact that Debian
- builds all of Tcl, Tk, Tkinter and Python with pthreads support.
- Under other Linux environments (such as Fedora Core 2/3), this option has
- caused random crashes and lockups of the Python interpreter.
- Under other operating systems (Mac OSX and Windows), you'll need to try
- it to find out, since currently no user reports are available.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- There is unfortunately no way for IPython to determine at run time whether
- 
-\family typewriter
--tk
-\family default
- will work reliably or not, so you will need to do some experiments before
- relying on it for regular work.
- 
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:cmd-line-opts}
-
-\end_inset
-
-Regular Options
-\end_layout
-
-\begin_layout Standard
-After the above threading options have been given, regular options can follow
- in any order.
- All options can be abbreviated to their shortest non-ambiguous form and
- are case-sensitive.
- One or two dashes can be used.
- Some options have an alternate short form, indicated after a 
-\family typewriter
-|
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Most options can also be set from your ipythonrc configuration file.
- See the provided example for more details on what the options do.
- Options given at the command line override the values set in the ipythonrc
- file.
-\end_layout
-
-\begin_layout Standard
-All options with a 
-\family typewriter
-[no]
-\family default
- prepended can be specified in negated form (
-\family typewriter
--nooption
-\family default
- instead of 
-\family typewriter
--option
-\family default
-) to turn the feature off.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--help
-\family default
-\series default
-: print a help message and exit.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--pylab:
-\family default
-\series default
- this can 
-\emph on
-only
-\emph default
- be given as the 
-\emph on
-first
-\emph default
- option passed to IPython (it will have no effect in any other position).
- It adds special support for the matplotlib library (
-\begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
-
-\end_inset
-
-), allowing interactive usage of any of its backends as defined in the user's
- 
-\family typewriter
-.matplotlibrc
-\family default
- file.
- It automatically activates GTK or WX threading for IPyhton if the choice
- of matplotlib backend requires it.
- It also modifies the 
-\family typewriter
-%run
-\family default
- command to correctly execute (without blocking) any matplotlib-based script
- which calls 
-\family typewriter
-show()
-\family default
- at the end.
- See Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:matplotlib-support}
-
-\end_inset
-
- for more details.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--autocall <val>:
-\family default
-\series default
- 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 
-\emph on
-smart
-\emph default
- autocall, where it is not applied if there are no more arguments on the
- line, and `2' for 
-\emph on
-full
-\emph default
- autocall, where all callable objects are automatically called (even if
- no arguments are present).
- The default is `1'.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]autoindent:
-\family default
-\series default
- Turn automatic indentation on/off.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]automagic
-\series default
-:
-\family default
- make magic commands automatic (without needing their first character to
- be 
-\family typewriter
-%
-\family default
-).
- Type 
-\family typewriter
-%magic
-\family default
- at the IPython prompt for more information.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]autoedit_syntax:
-\family default
-\series default
- When a syntax error occurs after editing a file, automatically open the
- file to the trouble causing line for convenient fixing.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]banner
-\series default
-:
-\family default
- Print the initial information banner (default on).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--c\InsetSpace ~
-<command>:
-\family default
-\series default
- execute the given command string, and set sys.argv to 
-\family typewriter
-['c']
-\family default
-.
- This is similar to the 
-\family typewriter
--c
-\family default
- option in the normal Python interpreter.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--cache_size|cs\InsetSpace ~
-<n>
-\series default
-:
-\family default
- size of the output cache (maximum number of entries to hold in memory).
- The default is 1000, you can change it permanently in your config file.
- Setting it to 0 completely disables the caching system, and the minimum
- value accepted is 20 (if you provide a value less than 20, it is reset
- to 0 and a warning is issued) This limit is defined because otherwise you'll
- spend more time re-flushing a too small cache than working.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--classic|cl
-\series default
-:
-\family default
- Gives IPython a similar feel to the classic Python prompt.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--colors\InsetSpace ~
-<scheme>:
-\family default
-\series default
- Color scheme for prompts and exception reporting.
- Currently implemented: NoColor, Linux and LightBG.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]color_info:
-\family default
-\series default
- IPython can display information about objects via a set of functions, and
- optionally can use colors for this, syntax highlighting source code and
- various other elements.
- However, because this information is passed through a pager (like 'less')
- and many pagers get confused with color codes, this option is off by default.
- You can test it and turn it on permanently in your ipythonrc file if it
- works for you.
- As a reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
- that in RedHat 7.2 doesn't.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Test it and turn it on permanently if it works with your system.
- The magic function 
-\family typewriter
-%color_info
-\family default
- allows you to toggle this interactively for testing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]debug
-\family default
-\series default
-: Show information about the loading process.
- Very useful to pin down problems with your configuration files or to get
- details about session restores.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]deep_reload
-\series default
-:
-\family default
- IPython can use the 
-\family typewriter
-deep_reload
-\family default
- module which reloads changes in modules recursively (it replaces the 
-\family typewriter
-reload()
-\family default
- function, so you don't need to change anything to use it).
- 
-\family typewriter
-deep_reload()
-\family default
- forces a full reload of modules whose code may have changed, which the
- default 
-\family typewriter
-reload()
-\family default
- function does not.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- When deep_reload is off, IPython will use the normal 
-\family typewriter
-reload()
-\family default
-, but deep_reload will still be available as 
-\family typewriter
-dreload()
-\family default
-.
- This feature is off by default [which means that you have both normal 
-\family typewriter
-reload()
-\family default
- and 
-\family typewriter
-dreload()
-\family default
-].
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--editor\InsetSpace ~
-<name>
-\family default
-\series default
-: Which editor to use with the 
-\family typewriter
-%edit
-\family default
- command.
- By default, IPython will honor your 
-\family typewriter
-EDITOR
-\family default
- environment variable (if not set, vi is the Unix default and notepad the
- Windows one).
- Since this editor is invoked on the fly by IPython and is meant for editing
- small code snippets, you may want to use a small, lightweight editor here
- (in case your default 
-\family typewriter
-EDITOR
-\family default
- is something like Emacs).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--ipythondir\InsetSpace ~
-<name>
-\series default
-:
-\family default
- name of your IPython configuration directory 
-\family typewriter
-IPYTHONDIR
-\family default
-.
- This can also be specified through the environment variable 
-\family typewriter
-IPYTHONDIR
-\family default
-.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--log|l
-\family default
-\series default
-: generate a log file of all input.
- The file is named 
-\family typewriter
-ipython_log.py
-\family default
- in your current directory (which prevents logs from multiple IPython sessions
- from trampling each other).
- You can use this to later restore a session by loading your logfile as
- a file to be executed with option 
-\family typewriter
--logplay
-\family default
- (see below).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--logfile|lf\InsetSpace ~
-<name>
-\series default
-: 
-\family default
-specify the name of your logfile.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--logplay|lp\InsetSpace ~
-<name>
-\series default
-:
-\family default
- you can replay a previous log.
- For restoring a session as close as possible to the state you left it in,
- use this option (don't just run the logfile).
- With 
-\family typewriter
--logplay
-\family default
-, IPython will try to reconstruct the previous working environment in full,
- not just execute the commands in the logfile.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- When a session is restored, logging is automatically turned on again with
- the name of the logfile it was invoked with (it is read from the log header).
- So once you've turned logging on for a session, you can quit IPython and
- reload it as many times as you want and it will continue to log its history
- and restore from the beginning every time.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Caveats: there are limitations in this option.
- The history variables 
-\family typewriter
-_i*
-\family default
-,
-\family typewriter
-_*
-\family default
- and 
-\family typewriter
-_dh
-\family default
- don't get restored properly.
- In the future we will try to implement full session saving by writing and
- retrieving a 'snapshot' of the memory state of IPython.
- But our first attempts failed because of inherent limitations of Python's
- Pickle module, so this may have to wait.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]messages
-\series default
-:
-\family default
- Print messages which IPython collects about its startup process (default
- on).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]pdb
-\family default
-\series default
-: Automatically call the pdb debugger after every uncaught exception.
- If you are used to debugging using pdb, this puts you automatically inside
- of it after any call (either in IPython or in code called by it) which
- triggers an exception which goes uncaught.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]pprint
-\series default
-:
-\family default
- ipython can optionally use the pprint (pretty printer) module for displaying
- results.
- pprint tends to give a nicer display of nested data structures.
- If you like it, you can turn it on permanently in your config file (default
- off).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--profile|p <name>
-\series default
-:
-\family default
- assume that your config file is 
-\family typewriter
-ipythonrc-<name>
-\family default
- (looks in current dir first, then in 
-\family typewriter
-IPYTHONDIR
-\family default
-).
- This is a quick way to keep and load multiple config files for different
- tasks, especially if you use the include option of config files.
- You can keep a basic 
-\family typewriter
-IPYTHONDIR/ipythonrc
-\family default
- file and then have other 'profiles' which include this one and load extra
- things for particular tasks.
- For example:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\InsetSpace ~
- 
-\family default
-1.
-
-\family typewriter
- $HOME/.ipython/ipythonrc
-\family default
- : load basic things you always want.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\InsetSpace ~
- 
-\family default
-2.
-
-\family typewriter
- $HOME/.ipython/ipythonrc-math
-\family default
- : load (1) and basic math-related modules.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\InsetSpace ~
- 
-\family default
-3.
-
-\family typewriter
- $HOME/.ipython/ipythonrc-numeric
-\family default
- : load (1) and Numeric and plotting modules.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Since it is possible to create an endless loop by having circular file
- inclusions, IPython will stop if it reaches 15 recursive inclusions.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--prompt_in1|pi1\InsetSpace ~
-<string>:
-\family default
-\series default
- Specify the string used for input prompts.
- Note that if you are using numbered prompts, the number is represented
- with a '
-\backslash
-#' in the string.
- Don't forget to quote strings with spaces embedded in them.
- Default: '
-\family typewriter
-In\InsetSpace ~
-[
-\backslash
-#]:
-\family default
-'.
- Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:prompts}
-
-\end_inset
-
- discusses in detail all the available escapes to customize your prompts.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--prompt_in2|pi2\InsetSpace ~
-<string>:
-\family default
-\series default
- Similar to the previous option, but used for the continuation prompts.
- The special sequence '
-\family typewriter
-
-\backslash
-D
-\family default
-' is similar to '
-\family typewriter
-
-\backslash
-#
-\family default
-', but with all digits replaced dots (so you can have your continuation
- prompt aligned with your input prompt).
- Default: '
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-.
-\backslash
-D.:
-\family default
-' (note three spaces at the start for alignment with '
-\family typewriter
-In\InsetSpace ~
-[
-\backslash
-#]
-\family default
-').
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--prompt_out|po\InsetSpace ~
-<string>:
-\family default
-\series default
- String used for output prompts, also uses numbers like 
-\family typewriter
-prompt_in1
-\family default
-.
- Default: '
-\family typewriter
-Out[
-\backslash
-#]:
-\family default
-'
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--quick
-\family default
-\series default
-: start in bare bones mode (no config file loaded).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--rcfile\InsetSpace ~
-<name>
-\series default
-:
-\family default
- name of your IPython resource configuration file.
- Normally IPython loads ipythonrc (from current directory) or
-\family typewriter
- IPYTHONDIR/ipythonrc
-\family default
-.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- If the loading of your config file fails, IPython starts with a bare bones
- configuration (no modules loaded at all).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--[no]readline
-\family default
-\series default
-: use the readline library, which is needed to support name completion and
- command history, among other things.
- It is enabled by default, but may cause problems for users of X/Emacs in
- Python comint or shell buffers.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Note that X/Emacs 'eterm' buffers (opened with 
-\family typewriter
-M-x\InsetSpace ~
-term
-\family default
-) support IPython's readline and syntax coloring fine, only 'emacs' (
-\family typewriter
-M-x\InsetSpace ~
-shell
-\family default
- and 
-\family typewriter
-C-c\InsetSpace ~
-!
-\family default
-) buffers do not.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--screen_length|sl\InsetSpace ~
-<n>
-\series default
-:
-\family default
- number of lines of your screen.
- This is used to control printing of very long strings.
- Strings longer than this number of lines will be sent through a pager instead
- of directly printed.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- 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.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--separate_in|si\InsetSpace ~
-<string>
-\series default
-:
-\family default
- separator before input prompts.
- Default: '
-\family typewriter
-
-\backslash
-n
-\family default
-'
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--separate_out|so\InsetSpace ~
-<string>
-\family default
-\series default
-: separator before output prompts.
- Default: nothing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--separate_out2|so2\InsetSpace ~
-<string>
-\series default
-:
-\family default
- separator after output prompts.
- Default: nothing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- For these three options, use the value 0 to specify no separator.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--nosep
-\series default
-: 
-\family default
-shorthand for 
-\family typewriter
-'-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'
-\family default
-.
- Simply removes all input/output separators.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--upgrade
-\family default
-\series default
-: allows you to upgrade your 
-\family typewriter
-IPYTHONDIR
-\family default
- configuration when you install a new version of IPython.
- Since new versions may include new command line options or example files,
- this copies updated ipythonrc-type files.
- However, it backs up (with a 
-\family typewriter
-.old
-\family default
- extension) all files which it overwrites so that you can merge back any
- customizations you might have in your personal files.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--Version
-\series default
-:
-\family default
- print version information and exit.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--wxversion\InsetSpace ~
-<string>:
-\family default
-\series default
- Select a specific version of wxPython (used in conjunction with 
-\family typewriter
--wthread
-\family default
-).
- Requires the wxversion module, part of recent wxPython distributions
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
--xmode\InsetSpace ~
-<modename>
-\series default
-:
-\family default
- Mode for exception reporting.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Valid modes: Plain, Context and Verbose.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Plain: similar to python's normal traceback printing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- Context: prints 5 lines of context source code around each line in the
- traceback.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- 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).
-\end_layout
-
-\begin_layout Section
-Interactive use
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Warning
-\series default
-: IPython relies on the existence of a global variable called 
-\family typewriter
-__IP
-\family default
- which controls the shell itself.
- If you redefine 
-\family typewriter
-__IP
-\family default
- to anything, bizarre behavior will quickly occur.
-\end_layout
-
-\begin_layout Standard
-Other than the above warning, IPython is meant to work as a drop-in replacement
- for the standard interactive interpreter.
- As such, any code which is valid python should execute normally under IPython
- (cases where this is not true should be reported as bugs).
- It does, however, offer many features which are not available at a standard
- python prompt.
- What follows is a list of these.
-\end_layout
-
-\begin_layout Subsection
-Caution for Windows users
-\end_layout
-
-\begin_layout Standard
-Windows, unfortunately, uses the `
-\family typewriter
-
-\backslash
-
-\family default
-' character as a path separator.
- This is a terrible choice, because `
-\family typewriter
-
-\backslash
-
-\family default
-' also represents the escape character in most modern programming languages,
- including Python.
- For this reason, issuing many of the commands discussed below (especially
- magics which affect the filesystem) with `
-\family typewriter
-
-\backslash
-
-\family default
-' in them will cause strange errors.
-\end_layout
-
-\begin_layout Standard
-A partial solution is to use instead the `
-\family typewriter
-/
-\family default
-' character as a path separator, which Windows recognizes in 
-\emph on
-most
-\emph default
- situations.
- However, in Windows commands `
-\family typewriter
-/
-\family default
-' 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:
-\newline
-
-\family typewriter
-%copy 
-\backslash
-opt/foo/bar.txt 
-\backslash
-tmp
-\end_layout
-
-\begin_layout Standard
-There is no sensible thing IPython can do to truly work around this flaw
- in Windows
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-If anyone comes up with a 
-\emph on
-clean
-\emph default
- solution which works consistently and does not negatively impact other
- platforms at all, I'll gladly accept a patch.
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:magic}
-
-\end_inset
-
-Magic command system
-\end_layout
-
-\begin_layout Standard
-IPython will treat any line whose first character is a 
-\family typewriter
-%
-\family default
- 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 
-\family typewriter
-%
-\family default
- character, but parameters are given without parentheses or quotes.
-\end_layout
-
-\begin_layout Standard
-Example: typing 
-\family typewriter
-'%cd mydir'
-\family default
- (without the quotes) changes you working directory to 
-\family typewriter
-'mydir'
-\family default
-, if it exists.
-\end_layout
-
-\begin_layout Standard
-If you have 'automagic' enabled (in your 
-\family typewriter
-ipythonrc
-\family default
- file, via the command line option 
-\family typewriter
--automagic 
-\family default
-or with the 
-\family typewriter
-%automagic
-\family default
- function), you don't need to type in the 
-\family typewriter
-%
-\family default
- explicitly.
- IPython will scan its internal list of magic functions and call one if
- it exists.
- With automagic on you can then just type '
-\family typewriter
-cd mydir
-\family default
-' to go to directory '
-\family typewriter
-mydir
-\family default
-'.
- 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
- 
-\family typewriter
-%
-\family default
- character at the beginning of the line.
-\end_layout
-
-\begin_layout Standard
-An example (with automagic on) should clarify all this:
-\end_layout
-
-\begin_layout LyX-Code
-In [1]: cd ipython # %cd is called by automagic
-\end_layout
-
-\begin_layout LyX-Code
-/home/fperez/ipython
-\end_layout
-
-\begin_layout LyX-Code
-In [2]: cd=1 # now cd is just a variable
-\end_layout
-
-\begin_layout LyX-Code
-In [3]: cd ..
- # and doesn't work as a function anymore
-\end_layout
-
-\begin_layout LyX-Code
-------------------------------------------------------------
-\end_layout
-
-\begin_layout LyX-Code
-    File "<console>", line 1
-\end_layout
-
-\begin_layout LyX-Code
-      cd ..
-\end_layout
-
-\begin_layout LyX-Code
-          ^
-\end_layout
-
-\begin_layout LyX-Code
-SyntaxError: invalid syntax
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-In [4]: %cd ..
- # but %cd always works
-\end_layout
-
-\begin_layout LyX-Code
-/home/fperez
-\end_layout
-
-\begin_layout LyX-Code
-In [5]: del cd # if you remove the cd variable
-\end_layout
-
-\begin_layout LyX-Code
-In [6]: cd ipython # automagic can work again
-\end_layout
-
-\begin_layout LyX-Code
-/home/fperez/ipython
-\end_layout
-
-\begin_layout Standard
-You can define your own magic functions to extend the system.
- The following example defines a new magic command, 
-\family typewriter
-%impall
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-import IPython.ipapi 
-\end_layout
-
-\begin_layout LyX-Code
-ip = IPython.ipapi.get()
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-def doimp(self, arg):
-\end_layout
-
-\begin_layout LyX-Code
-    ip = self.api
-\end_layout
-
-\begin_layout LyX-Code
-    ip.ex("import %s; reload(%s); from %s import *" % (
-\end_layout
-
-\begin_layout LyX-Code
-    arg,arg,arg)
-\end_layout
-
-\begin_layout LyX-Code
-    )
-\end_layout
-
-\begin_layout LyX-Code
-ip.expose_magic('impall', doimp)
-\end_layout
-
-\begin_layout Standard
-You can also define your own aliased names for magic functions.
- In your 
-\family typewriter
-ipythonrc
-\family default
- file, placing a line like:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-execute __IP.magic_cl = __IP.magic_clear
-\end_layout
-
-\begin_layout Standard
-will define 
-\family typewriter
-%cl
-\family default
- as a new name for 
-\family typewriter
-%clear
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Type 
-\family typewriter
-%magic
-\family default
- for more information, including a list of all available magic functions
- at any time and their docstrings.
- You can also type 
-\family typewriter
-%magic_function_name?
-\family default
- (see sec.
- 
-\begin_inset LatexCommand \ref{sec:dyn-object-info}
-
-\end_inset
-
- for information on the 
-\family typewriter
-'?'
-\family default
- system) to get information about any particular magic function you are
- interested in.
-\end_layout
-
-\begin_layout Subsubsection
-Magic commands
-\end_layout
-
-\begin_layout Standard
-The rest of this section is automatically generated for each release from
- the docstrings in the IPython code.
- Therefore the formatting is somewhat minimal, but this method has the advantage
- of having information always in sync with the code.
-\end_layout
-
-\begin_layout Standard
-A list of all the magic commands available in IPython's 
-\emph on
-default
-\emph default
- installation follows.
- This is similar to what you'll see by simply typing 
-\family typewriter
-%magic
-\family default
- at the prompt, but that will also give you information about magic commands
- you may have added as part of your personal customizations.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \input{magic.tex}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Access to the standard Python help
-\end_layout
-
-\begin_layout Standard
-As of Python 2.1, a help system is available with access to object docstrings
- and the Python manuals.
- Simply type 
-\family typewriter
-'help'
-\family default
- (no quotes) to access it.
- You can also type 
-\family typewriter
-help(object)
-\family default
- to obtain information about a given object, and 
-\family typewriter
-help('keyword')
-\family default
- for information on a keyword.
- As noted in sec.
- 
-\begin_inset LatexCommand \ref{sec:help-access}
-
-\end_inset
-
-, you need to properly configure your environment variable 
-\family typewriter
-PYTHONDOCS
-\family default
- for this feature to work correctly.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:dyn-object-info}
-
-\end_inset
-
-Dynamic object information
-\end_layout
-
-\begin_layout Standard
-Typing 
-\family typewriter
-?word
-\family default
- or 
-\family typewriter
-word?
-\family default
- prints detailed information about an object.
- If certain strings in the object are too long (docstrings, code, etc.) they
- get snipped in the center for brevity.
- This system gives access variable types and values, full source code for
- any object (if available), function prototypes and other useful information.
-\end_layout
-
-\begin_layout Standard
-Typing 
-\family typewriter
-??word
-\family default
- or 
-\family typewriter
-word??
-\family default
- gives access to the full information without snipping long strings.
- Long strings are sent to the screen through the 
-\family typewriter
-less
-\family default
- pager if longer than the screen and printed otherwise.
- On systems lacking the 
-\family typewriter
-less
-\family default
- command, IPython uses a very basic internal pager.
-\end_layout
-
-\begin_layout Standard
-The following magic functions are particularly useful for gathering information
- about your working environment.
- You can get more details by typing 
-\family typewriter
-%magic
-\family default
- or querying them individually (use 
-\family typewriter
-%function_name?
-\family default
- with or without the 
-\family typewriter
-%
-\family default
-), this is just a summary:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-%pdoc\InsetSpace ~
-<object>
-\family default
-\series default
-: 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 constructo
-r docstrings.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-%pdef\InsetSpace ~
-<object>
-\family default
-\series default
-: Print the definition header for any callable object.
- If the object is a class, print the constructor information.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-%psource\InsetSpace ~
-<object>
-\family default
-\series default
-: Print (or run through a pager if too long) the source code for an object.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-%pfile\InsetSpace ~
-<object>
-\family default
-\series default
-: Show the entire source file where an object was defined via a pager, opening
- it at the line where the object definition begins.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-%who/%whos
-\family default
-\series default
-: These functions give information about identifiers you have defined interactiv
-ely (not things you loaded or defined in your configuration files).
- 
-\family typewriter
-%who
-\family default
- just prints a list of identifiers and 
-\family typewriter
-%whos
-\family default
- prints a table with some basic details about each identifier.
-\end_layout
-
-\begin_layout Standard
-Note that the dynamic object information functions (
-\family typewriter
-?/??, %pdoc, %pfile, %pdef, %psource
-\family default
-) give you access to documentation even on things which are not really defined
- as separate identifiers.
- Try for example typing 
-\family typewriter
-{}.get?
-\family default
- or after doing 
-\family typewriter
-import os
-\family default
-, type 
-\family typewriter
-os.path.abspath??
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:readline}
-
-\end_inset
-
-Readline-based features
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Subsubsection
-Command line completion
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Subsubsection
-Search command history
-\end_layout
-
-\begin_layout Standard
-IPython provides two ways for searching through previous input and thus
- reduce the need for repetitive typing:
-\end_layout
-
-\begin_layout Enumerate
-Start typing, and then use 
-\family typewriter
-Ctrl-p
-\family default
- (previous,up) and 
-\family typewriter
-Ctrl-n
-\family default
- (next,down) to search through only the history items that match what you've
- typed so far.
- If you use 
-\family typewriter
-Ctrl-p/Ctrl-n
-\family default
- at a blank prompt, they just behave like normal arrow keys.
-\end_layout
-
-\begin_layout Enumerate
-Hit 
-\family typewriter
-Ctrl-r
-\family default
-: 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.
-\end_layout
-
-\begin_layout Subsubsection
-Persistent command history across sessions
-\end_layout
-
-\begin_layout Standard
-IPython will save your input history when it leaves and reload it next time
- you restart it.
- By default, the history file is named 
-\family typewriter
-$IPYTHONDIR/history
-\family default
-, but if you've loaded a named profile, '
-\family typewriter
--PROFILE_NAME
-\family default
-' is appended to the name.
- This allows you to keep separate histories related to various tasks: commands
- related to numerical work will not be clobbered by a system shell history,
- for example.
-\end_layout
-
-\begin_layout Subsubsection
-Autoindent
-\end_layout
-
-\begin_layout Standard
-IPython can recognize lines ending in ':' and indent the next line, while
- also un-indenting automatically after 'raise' or 'return'.
- 
-\end_layout
-
-\begin_layout Standard
-This feature uses the readline library, so it will honor your 
-\family typewriter
-~/.inputrc
-\family default
- configuration (or whatever file your 
-\family typewriter
-INPUTRC
-\family default
- variable points to).
- Adding the following lines to your 
-\family typewriter
-.inputrc
-\family default
- file can make indenting/unindenting more convenient (
-\family typewriter
-M-i
-\family default
- indents, 
-\family typewriter
-M-u
-\family default
- unindents):
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-$if Python
-\newline
-"
-\backslash
-M-i": "\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-" 
-\newline
-"
-\backslash
-M-u": "
-\backslash
-d
-\backslash
-d
-\backslash
-d
-\backslash
-d" 
-\newline
-$endif
-\end_layout
-
-\begin_layout Standard
-Note that there are 4 spaces between the quote marks after 
-\family typewriter
-"M-i"
-\family default
- above.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Warning:
-\series default
- this feature is ON by default, but it can cause problems with the pasting
- of multi-line indented code (the pasted code gets re-indented on each line).
- A magic function 
-\family typewriter
-%autoindent
-\family default
- allows you to toggle it on/off at runtime.
- You can also disable it permanently on in your 
-\family typewriter
-ipythonrc
-\family default
- file (set 
-\family typewriter
-autoindent 0
-\family default
-).
-\end_layout
-
-\begin_layout Subsubsection
-Customizing readline behavior
-\end_layout
-
-\begin_layout Standard
-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 
-\family typewriter
-ipythonrc
-\family default
- configuration file (note that these options can 
-\emph on
-not
-\emph default
- be specified at the command line):
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-readline_parse_and_bind:
-\family default
-\series default
- this option can appear as many times as you want, each time defining a
- string to be executed via a 
-\family typewriter
-readline.parse_and_bind()
-\family default
- 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.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-readline_remove_delims:
-\family default
-\series default
- 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.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-readline_omit__names
-\family default
-\series default
-: when tab-completion is enabled, hitting 
-\family typewriter
-<tab>
-\family default
- after a '
-\family typewriter
-.
-\family default
-' in a name will complete all attributes of an object, including all the
- special methods whose names include double underscores (like 
-\family typewriter
-__getitem__
-\family default
- or 
-\family typewriter
-__class__
-\family default
-).
- If you'd rather not see these names by default, you can set this option
- to 1.
- Note that even when this option is set, you can still see those names by
- explicitly typing a 
-\family typewriter
-_
-\family default
- after the period and hitting 
-\family typewriter
-<tab>
-\family default
-: '
-\family typewriter
-name._<tab>
-\family default
-' will always complete attribute names starting with '
-\family typewriter
-_
-\family default
-'.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-\InsetSpace ~
- This option is off by default so that new users see all attributes of any
- objects they are dealing with.
-\end_layout
-
-\begin_layout Standard
-You will find the default values along with a corresponding detailed explanation
- in your 
-\family typewriter
-ipythonrc
-\family default
- file.
-\end_layout
-
-\begin_layout Subsection
-Session logging and restoring
-\end_layout
-
-\begin_layout Standard
-You can log all input from a session either by starting IPython with the
- command line switches 
-\family typewriter
--log
-\family default
- or 
-\family typewriter
--logfile 
-\family default
-(see sec.
- 
-\begin_inset LatexCommand \ref{sec:cmd-line-opts}
-
-\end_inset
-
-)or by activating the logging at any moment with the magic function 
-\family typewriter
-%logstart
-\family default
-.
- 
-\end_layout
-
-\begin_layout Standard
-Log files can later be reloaded with the 
-\family typewriter
--logplay
-\family default
- option and IPython will attempt to 'replay' the log by executing all the
- lines in it, thus restoring the state of a previous session.
- This feature is not quite perfect, but can still be useful in many cases.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%logstart
-\family default
- function for activating logging in mid-session is used as follows:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-%logstart [log_name [log_mode]]
-\end_layout
-
-\begin_layout Standard
-If no name is given, it defaults to a file named 
-\family typewriter
-'log'
-\family default
- in your IPYTHONDIR directory, in 
-\family typewriter
-'rotate'
-\family default
- mode (see below).
-\end_layout
-
-\begin_layout Standard
-'
-\family typewriter
-%logstart name
-\family default
-' saves to file 
-\family typewriter
-'name'
-\family default
- in 
-\family typewriter
-'backup'
-\family default
- mode.
- It saves your history up to that point and then continues logging.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-%logstart
-\family default
- takes a second optional parameter: logging mode.
- This can be one of (note that the modes are given unquoted):
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-over
-\family default
-: overwrite existing 
-\family typewriter
-log_name
-\family default
-.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-backup
-\family default
-: rename (if exists) to 
-\family typewriter
-log_name~
-\family default
- and start 
-\family typewriter
-log_name
-\family default
-.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-append
-\family default
-: well, that says it.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-rotate
-\family default
-: create rotating logs 
-\family typewriter
-log_name
-\family default
-.
-\family typewriter
-1~
-\family default
-, 
-\family typewriter
-log_name.2~
-\family default
-, etc.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%logoff
-\family default
- and 
-\family typewriter
-%logon
-\family default
- functions allow you to temporarily stop and resume logging to a file which
- had previously been started with 
-\family typewriter
-%logstart
-\family default
-.
- They will fail (with an explanation) if you try to use them before logging
- has been started.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sub:System-shell-access}
-
-\end_inset
-
-System shell access
-\end_layout
-
-\begin_layout Standard
-Any input line beginning with a 
-\family typewriter
-!
-\family default
- character is passed verbatim (minus the 
-\family typewriter
-!
-\family default
-, of course) to the underlying operating system.
- For example, typing 
-\family typewriter
-!ls
-\family default
- will run 
-\family typewriter
-'ls'
-\family default
- in the current directory.
-\end_layout
-
-\begin_layout Subsubsection
-Manual capture of command output
-\end_layout
-
-\begin_layout Standard
-If the input line begins with 
-\emph on
-two
-\emph default
- exclamation marks, 
-\family typewriter
-!!
-\family default
-, the command is executed but its output is captured and returned as a python
- list, split on newlines.
- Any output sent by the subprocess to standard error is printed separately,
- so that the resulting list only captures standard output.
- The 
-\family typewriter
-!!
-\family default
- syntax is a shorthand for the 
-\family typewriter
-%sx
-\family default
- magic command.
-\end_layout
-
-\begin_layout Standard
-Finally, the 
-\family typewriter
-%sc
-\family default
- magic (short for `shell capture') is similar to 
-\family typewriter
-%sx
-\family default
-, but allowing more fine-grained control of the capture details, and storing
- the result directly into a named variable.
-\end_layout
-
-\begin_layout Standard
-See Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
- for details on the magics 
-\family typewriter
-%sc
-\family default
- and 
-\family typewriter
-%sx
-\family default
-, or use IPython's own help (
-\family typewriter
-sc?
-\family default
- and 
-\family typewriter
-sx?
-\family default
-) for further details.
-\end_layout
-
-\begin_layout Standard
-IPython also allows you to expand the value of python variables when making
- system calls.
- Any python variable or expression which you prepend with 
-\family typewriter
-$
-\family default
- will get expanded before the system call is made.
- 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [1]: pyvar='Hello world'
-\newline
-In [2]: !echo "A python variable: $pyvar" 
-\newline
-A python
- variable: Hello world
-\end_layout
-
-\begin_layout Standard
-If you want the shell to actually see a literal 
-\family typewriter
-$
-\family default
-, you need to type it twice:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [3]: !echo "A system variable: $$HOME" 
-\newline
-A system variable: /home/fperez
-\end_layout
-
-\begin_layout Standard
-You can pass arbitrary expressions, though you'll need to delimit them with
- 
-\family typewriter
-{}
-\family default
- if there is ambiguity as to the extent of the expression:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [5]: x=10
-\newline
-In [6]: y=20
-\newline
-In [13]: !echo $x+y 
-\newline
-10+y 
-\newline
-In [7]: !echo ${x+y} 
-\newline
-30
- 
-\end_layout
-
-\begin_layout Standard
-Even object attributes can be expanded:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [12]: !echo $sys.argv 
-\newline
-[/home/fperez/usr/bin/ipython] 
-\end_layout
-
-\begin_layout Subsection
-System command aliases
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%alias
-\family default
- magic function and the 
-\family typewriter
-alias
-\family default
- option in the 
-\family typewriter
-ipythonrc
-\family default
- configuration file allow you to define magic functions which are in fact
- system shell commands.
- These aliases can have parameters.
- 
-\end_layout
-
-\begin_layout Standard
-'
-\family typewriter
-%alias alias_name cmd
-\family default
-' defines '
-\family typewriter
-alias_name
-\family default
-' as an alias for '
-\family typewriter
-cmd
-\family default
-' 
-\end_layout
-
-\begin_layout Standard
-Then, typing '
-\family typewriter
-%alias_name params
-\family default
-' will execute the system command '
-\family typewriter
-cmd params
-\family default
-' (from your underlying operating system).
- 
-\end_layout
-
-\begin_layout Standard
-You can also define aliases with parameters using 
-\family typewriter
-%s
-\family default
- specifiers (one per parameter).
- The following example defines the 
-\family typewriter
-%parts
-\family default
- function as an alias to the command '
-\family typewriter
-echo first %s second %s
-\family default
-' where each 
-\family typewriter
-%s
-\family default
- will be replaced by a positional parameter to the call to 
-\family typewriter
-%parts:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [1]: alias parts echo first %s second %s
-\newline
-In [2]: %parts A B
-\newline
-first A second
- B 
-\newline
-In [3]: %parts A 
-\newline
-Incorrect number of arguments: 2 expected.
- 
-\newline
-parts is an alias to: 'echo first %s second %s' 
-\end_layout
-
-\begin_layout Standard
-If called with no parameters, 
-\family typewriter
-%alias
-\family default
- prints the table of currently defined aliases.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-%rehash/rehashx
-\family default
- magics allow you to load your entire 
-\family typewriter
-$PATH
-\family default
- as ipython aliases.
- See their respective docstrings (or sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
- for further details).
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:dreload}
-
-\end_inset
-
-Recursive reload
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-dreload
-\family default
- function does a recursive reload of a module: changes made to the module
- since you imported will actually be available without having to exit.
-\end_layout
-
-\begin_layout Subsection
-Verbose and colored exception traceback printouts
-\end_layout
-
-\begin_layout Standard
-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 
-\family typewriter
-%run
-\family default
- 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.
-\end_layout
-
-\begin_layout Standard
-See the magic 
-\family typewriter
-xmode
-\family default
- and 
-\family typewriter
-colors
-\family default
- functions for details (just type 
-\family typewriter
-%magic
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-These features are basically a terminal version of Ka-Ping Yee's 
-\family typewriter
-cgitb
-\family default
- module, now part of the standard Python library.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:cache_input}
-
-\end_inset
-
-Input caching system
-\end_layout
-
-\begin_layout Standard
-IPython offers numbered prompts (In/Out) with input and output caching.
- All input is saved and can be retrieved as variables (besides the usual
- arrow key recall).
-\end_layout
-
-\begin_layout Standard
-The following GLOBAL variables always exist (so don't overwrite them!):
- 
-\family typewriter
-_i
-\family default
-: stores previous input.
- 
-\family typewriter
-_ii
-\family default
-: next previous.
- 
-\family typewriter
-_iii
-\family default
-: next-next previous.
- 
-\family typewriter
-_ih
-\family default
- : a list of all input 
-\family typewriter
-_ih[n]
-\family default
- is the input from line 
-\family typewriter
-n
-\family default
- and this list is aliased to the global variable 
-\family typewriter
-In
-\family default
-.
- If you overwrite 
-\family typewriter
-In
-\family default
- with a variable of your own, you can remake the assignment to the internal
- list with a simple 
-\family typewriter
-'In=_ih'
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Additionally, global variables named 
-\family typewriter
-_i<n>
-\family default
- are dynamically created (
-\family typewriter
-<n>
-\family default
- being the prompt counter), such that 
-\newline
-
-\family typewriter
-_i<n> == _ih[<n>] == In[<n>].
-\end_layout
-
-\begin_layout Standard
-For example, what you typed at prompt 14 is available as 
-\family typewriter
-_i14,
-\family default
- 
-\family typewriter
-_ih[14]
-\family default
- and 
-\family typewriter
-In[14]
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-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 
-\family typewriter
-'exec _i9'
-\family default
- will re-execute the contents of input prompt 9, '
-\family typewriter
-exec In[9:14]+In[18]
-\family default
-' will re-execute lines 9 through 13 and line 18).
-\end_layout
-
-\begin_layout Standard
-You can also re-execute multiple lines of input easily by using the magic
- 
-\family typewriter
-%macro
-\family default
- function (which automates the process and allows re-execution without having
- to type '
-\family typewriter
-exec
-\family default
-' every time).
- The macro system also allows you to re-execute previous lines which include
- magic function calls (which require special processing).
- Type 
-\family typewriter
-%macro?
-\family default
- or see sec.
- 
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
- for more details on the macro system.
-\end_layout
-
-\begin_layout Standard
-A history function 
-\family typewriter
-%hist
-\family default
- allows you to see any part of your input history by printing a range of
- the 
-\family typewriter
-_i
-\family default
- variables.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:cache_output}
-
-\end_inset
-
-Output caching system
-\end_layout
-
-\begin_layout Standard
-For output that is returned from actions, a system similar to the input
- cache exists but using 
-\family typewriter
-_
-\family default
- instead of 
-\family typewriter
-_i
-\family default
-.
- Only actions that produce a result (NOT assignments, for example) are cached.
- If you are familiar with Mathematica, IPython's 
-\family typewriter
-_
-\family default
- variables behave exactly like Mathematica's 
-\family typewriter
-%
-\family default
- variables.
-\end_layout
-
-\begin_layout Standard
-The following GLOBAL variables always exist (so don't overwrite them!):
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-_
-\family default
-\series default
- (a 
-\emph on
-single
-\emph default
- underscore) : stores previous output, like Python's default interpreter.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-__
-\family default
-\series default
- (two underscores): next previous.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-___
-\family default
-\series default
- (three underscores): next-next previous.
-\end_layout
-
-\begin_layout Standard
-Additionally, global variables named 
-\family typewriter
-_<n> 
-\family default
-are dynamically created (
-\family typewriter
-<n>
-\family default
- being the prompt counter), such that the result of output 
-\family typewriter
-<n>
-\family default
- is always available as 
-\family typewriter
-_<n>
-\family default
- (don't use the angle brackets, just the number, e.g.
- 
-\family typewriter
-_21
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-These global variables are all stored in a global dictionary (not a list,
- since it only has entries for lines which returned a result) available
- under the names 
-\family typewriter
-_oh
-\family default
- and 
-\family typewriter
-Out
-\family default
- (similar to 
-\family typewriter
-_ih
-\family default
- and 
-\family typewriter
-In
-\family default
-).
- So the output from line 12 can be obtained as 
-\family typewriter
-_12
-\family default
-, 
-\family typewriter
-Out[12]
-\family default
- or 
-\family typewriter
-_oh[12]
-\family default
-.
- If you accidentally overwrite the 
-\family typewriter
-Out
-\family default
- variable you can recover it by typing 
-\family typewriter
-'Out=_oh
-\family default
-' at the prompt.
-\end_layout
-
-\begin_layout Standard
-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 
-\family typewriter
-ipythonrc
-\family default
- file) 
-\family typewriter
-cache_size
-\family default
-.
- If you set it to 0, the whole system is completely disabled and the prompts
- revert to the classic 
-\family typewriter
-'>>>'
-\family default
- of normal Python.
-\end_layout
-
-\begin_layout Subsection
-Directory history
-\end_layout
-
-\begin_layout Standard
-Your history of visited directories is kept in the global list 
-\family typewriter
-_dh
-\family default
-, and the magic 
-\family typewriter
-%cd
-\family default
- command can be used to go to any entry in that list.
- The 
-\family typewriter
-%dhist
-\family default
- command allows you to view this history.
-\end_layout
-
-\begin_layout Subsection
-Automatic parentheses and quotes
-\end_layout
-
-\begin_layout Standard
-These features were adapted from Nathan Gray's LazyPython.
- They are meant to allow less typing for common situations.
-\end_layout
-
-\begin_layout Subsubsection
-Automatic parentheses
-\end_layout
-
-\begin_layout Standard
-Callable objects (i.e.
- functions, methods, etc) can be invoked like this (notice the commas between
- the arguments):
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> callable_ob arg1, arg2, arg3 
-\end_layout
-
-\begin_layout Standard
-and the input will be translated to this: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
---> callable_ob(arg1, arg2, arg3) 
-\end_layout
-
-\begin_layout Standard
-You can force automatic parentheses by using '/' as the first character
- of a line.
- For example:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> /globals # becomes 'globals()' 
-\end_layout
-
-\begin_layout Standard
-Note that the '/' MUST be the first character on the line! This won't work:
- 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> print /globals # syntax error
-\end_layout
-
-\begin_layout Standard
-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): 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [1]: zip (1,2,3),(4,5,6) # won't work 
-\end_layout
-
-\begin_layout Standard
-but this will work: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [2]: /zip (1,2,3),(4,5,6)
-\newline
-------> zip ((1,2,3),(4,5,6)) 
-\newline
-Out[2]= [(1, 4),
- (2, 5), (3, 6)] 
-\end_layout
-
-\begin_layout Standard
-IPython tells you that it has altered your command line by displaying the
- new command line preceded by 
-\family typewriter
--->
-\family default
-.
- e.g.: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [18]: callable list
-\newline
--------> callable (list)
-\end_layout
-
-\begin_layout Subsubsection
-Automatic quoting 
-\end_layout
-
-\begin_layout Standard
-You can force automatic quoting of a function's arguments by using 
-\family typewriter
-`,'
-\family default
- or 
-\family typewriter
-`;'
-\family default
- as the first character of a line.
- For example: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> ,my_function /home/me # becomes my_function("/home/me") 
-\end_layout
-
-\begin_layout Standard
-If you use 
-\family typewriter
-`;'
-\family default
- instead, the whole argument is quoted as a single string (while 
-\family typewriter
-`,'
-\family default
- splits on whitespace):
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> ,my_function a b c # becomes my_function("a","b","c")
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> ;my_function a b c # becomes my_function("a b c")
-\end_layout
-
-\begin_layout Standard
-Note that the `
-\family typewriter
-,
-\family default
-' or `
-\family typewriter
-;
-\family default
-' MUST be the first character on the line! This won't work: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
->>> x = ,my_function /home/me # syntax error
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:customization}
-
-\end_inset
-
-Customization
-\end_layout
-
-\begin_layout Standard
-As we've already mentioned, IPython reads a configuration file which can
- be specified at the command line (
-\family typewriter
--rcfile
-\family default
-) or which by default is assumed to be called 
-\family typewriter
-ipythonrc
-\family default
-.
- Such a file is looked for in the current directory where IPython is started
- and then in your 
-\family typewriter
-IPYTHONDIR
-\family default
-, which allows you to have local configuration files for specific projects.
- In this section we will call these types of configuration files simply
- rcfiles (short for resource configuration file).
-\end_layout
-
-\begin_layout Standard
-The syntax of an rcfile is one of key-value pairs separated by whitespace,
- one per line.
- Lines beginning with a 
-\family typewriter
-#
-\family default
- are ignored as comments, but comments can 
-\series bold
-not
-\series default
- be put on lines with data (the parser is fairly primitive).
- Note that these are not python files, and this is deliberate, because it
- allows us to do some things which would be quite tricky to implement if
- they were normal python files.
-\end_layout
-
-\begin_layout Standard
-First, an rcfile can contain permanent default values for almost all command
- line options (except things like 
-\family typewriter
--help
-\family default
- or 
-\family typewriter
--Version
-\family default
-).
- Sec\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:cmd-line-opts}
-
-\end_inset
-
- contains a description of all command-line options.
- However, values you explicitly specify at the command line override the
- values defined in the rcfile.
-\end_layout
-
-\begin_layout Standard
-Besides command line option values, the rcfile can specify values for certain
- extra special options which are not available at the command line.
- These options are briefly described below.
- 
-\end_layout
-
-\begin_layout Standard
-Each of these options may appear as many times as you need it in the file.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-include\InsetSpace ~
-<file1>\InsetSpace ~
-<file2>\InsetSpace ~
-...
-\family default
-\series default
-: you can name 
-\emph on
-other 
-\emph default
-rcfiles you want to recursively load up to 15 levels (don't use the 
-\family typewriter
-<>
-\family default
- brackets in your names!).
- This feature allows you to define a 'base' rcfile with general options
- and special-purpose files which can be loaded only when needed with particular
- configuration options.
- To make this more convenient, IPython accepts the 
-\family typewriter
--profile <name>
-\family default
- option (abbreviates to 
-\family typewriter
--p <name
-\family default
->)
-\family typewriter
- which
-\family default
- tells it to look for an rcfile named 
-\family typewriter
-ipythonrc-<name>
-\family default
-.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_mod\InsetSpace ~
-<mod1>\InsetSpace ~
-<mod2>\InsetSpace ~
-...
-\family default
-\series default
-: import modules with '
-\family typewriter
-import
-\family default
- 
-\family typewriter
-<mod1>,<mod2>,...
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_some\InsetSpace ~
-<mod>\InsetSpace ~
-<f1>\InsetSpace ~
-<f2>\InsetSpace ~
-...
-\family default
-\series default
-: import functions with '
-\family typewriter
-from <mod> import
-\family default
- 
-\family typewriter
-<f1>,<f2>,...
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_all\InsetSpace ~
-<mod1>\InsetSpace ~
-<mod2>\InsetSpace ~
-...
-\family default
-\series default
-: for each module listed import functions with '
-\family typewriter
-from <mod> import *
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-execute\InsetSpace ~
-<python\InsetSpace ~
-code>
-\family default
-\series default
-: give any single-line python code to be executed.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-execfile\InsetSpace ~
-<filename>
-\family default
-\series default
-: execute the python file given with an '
-\family typewriter
-execfile(filename)
-\family default
-' command.
- Username expansion is performed on the given names.
- So if you need any amount of extra fancy customization that won't fit in
- any of the above 'canned' options, you can just put it in a separate python
- file and execute it.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-alias\InsetSpace ~
-<alias_def>
-\family default
-\series default
-: this is equivalent to calling '
-\family typewriter
-%alias\InsetSpace ~
-<alias_def>
-\family default
-' at the IPython command line.
- This way, from within IPython you can do common system tasks without having
- to exit it or use the 
-\family typewriter
-!
-\family default
- escape.
- IPython isn't meant to be a shell replacement, but it is often very useful
- to be able to do things with files while testing code.
- This gives you the flexibility to have within IPython any aliases you may
- be used to under your normal system shell.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:ipytonrc-sample}
-
-\end_inset
-
-Sample 
-\family typewriter
-ipythonrc
-\family default
- file
-\end_layout
-
-\begin_layout Standard
-The default rcfile, called 
-\family typewriter
-ipythonrc
-\family default
- and supplied in your 
-\family typewriter
-IPYTHONDIR 
-\family default
-directory contains lots of comments on all of these options.
- We reproduce it here for reference:
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-codelist{../IPython/UserConfig/ipythonrc}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:prompts}
-
-\end_inset
-
-Fine-tuning your prompt
-\end_layout
-
-\begin_layout Standard
-IPython's prompts can be customized using a syntax similar to that of the
- 
-\family typewriter
-bash
-\family default
- shell.
- Many of 
-\family typewriter
-bash
-\family default
-'s escapes are supported, as well as a few additional ones.
- We list them below:
-\end_layout
-
-\begin_layout Description
-
-\backslash
-# the prompt/history count number.
- This escape is automatically wrapped in the coloring codes for the currently
- active color scheme.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-N the 'naked' prompt/history count number: this is just the number itself,
- without any coloring applied to it.
- This lets you produce numbered prompts with your own colors.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-D the prompt/history count, with the actual digits replaced by dots.
- Used mainly in continuation prompts (prompt_in2)
-\end_layout
-
-\begin_layout Description
-
-\backslash
-w the current working directory
-\end_layout
-
-\begin_layout Description
-
-\backslash
-W the basename of current working directory
-\end_layout
-
-\begin_layout Description
-
-\backslash
-X
-\emph on
-n
-\emph default
- where 
-\begin_inset Formula $n=0\ldots5.$
-\end_inset
-
- The current working directory, with 
-\family typewriter
-$HOME
-\family default
- replaced by 
-\family typewriter
-~
-\family default
-, and filtered out to contain only 
-\begin_inset Formula $n$
-\end_inset
-
- path elements
-\end_layout
-
-\begin_layout Description
-
-\backslash
-Y
-\emph on
-n
-\emph default
- Similar to 
-\backslash
-X
-\emph on
-n
-\emph default
-, but with the 
-\begin_inset Formula $n+1$
-\end_inset
-
- element included if it is 
-\family typewriter
-~
-\family default
- (this is similar to the behavior of the %c
-\emph on
-n
-\emph default
- escapes in 
-\family typewriter
-tcsh
-\family default
-)
-\end_layout
-
-\begin_layout Description
-
-\backslash
-u the username of the current user
-\end_layout
-
-\begin_layout Description
-
-\backslash
-$ if the effective UID is 0, a #, otherwise a $
-\end_layout
-
-\begin_layout Description
-
-\backslash
-h the hostname up to the first `.'
-\end_layout
-
-\begin_layout Description
-
-\backslash
-H the hostname
-\end_layout
-
-\begin_layout Description
-
-\backslash
-n a newline
-\end_layout
-
-\begin_layout Description
-
-\backslash
-r a carriage return
-\end_layout
-
-\begin_layout Description
-
-\backslash
-v IPython version string
-\end_layout
-
-\begin_layout Standard
-In addition to these, ANSI color escapes can be insterted into the prompts,
- as 
-\family typewriter
-
-\backslash
-C_
-\emph on
-ColorName
-\family default
-\emph default
-.
- The list of valid color names is: Black, Blue, Brown, Cyan, DarkGray, Green,
- LightBlue, LightCyan, LightGray, LightGreen, LightPurple, LightRed, NoColor,
- Normal, Purple, Red, White, Yellow.
-\end_layout
-
-\begin_layout Standard
-Finally, IPython supports the evaluation of arbitrary expressions in your
- prompt string.
- The prompt strings are evaluated through the syntax of PEP 215, but basically
- you can use 
-\family typewriter
-$x.y
-\family default
- to expand the value of 
-\family typewriter
-x.y
-\family default
-, and for more complicated expressions you can use braces: 
-\family typewriter
-${foo()+x}
-\family default
- will call function 
-\family typewriter
-foo
-\family default
- and add to it the value of 
-\family typewriter
-x
-\family default
-, before putting the result into your prompt.
- For example, using 
-\newline
-
-\family typewriter
-prompt_in1 '${commands.getoutput("uptime")}
-\backslash
-nIn [
-\backslash
-#]: '
-\newline
-
-\family default
-will print the result of the uptime command on each prompt (assuming the
- 
-\family typewriter
-commands
-\family default
- module has been imported in your 
-\family typewriter
-ipythonrc
-\family default
- file).
-\end_layout
-
-\begin_layout Subsubsection
-Prompt examples
-\end_layout
-
-\begin_layout Standard
-The following options in an ipythonrc file will give you IPython's default
- prompts:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-prompt_in1 'In [
-\backslash
-#]:'
-\newline
-prompt_in2 '\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-.
-\backslash
-D.:'
-\newline
-prompt_out 'Out[
-\backslash
-#]:'
-\end_layout
-
-\begin_layout Standard
-which look like this:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [1]: 1+2
-\newline
-Out[1]: 3
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [2]: for i in (1,2,3):
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-...: \InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-print i,
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-...:
-\newline
-1 2 3
-\end_layout
-
-\begin_layout Standard
-These will give you a very colorful prompt with path information:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-#prompt_in1 '
-\backslash
-C_Red
-\backslash
-u
-\backslash
-C_Blue[
-\backslash
-C_Cyan
-\backslash
-Y1
-\backslash
-C_Blue]
-\backslash
-C_LightGreen
-\backslash
-#>'
-\newline
-prompt_in2 ' ..
-\backslash
-D>'
-\newline
-prompt_out '<
-\backslash
-#>' 
-\end_layout
-
-\begin_layout Standard
-which look like this:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-\color red
-fperez
-\color blue
-[
-\color cyan
-~/ipython
-\color blue
-]
-\color green
-1>
-\color none
- 1+2
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-
-\color red
-<1>
-\color none
- 3
-\newline
-
-\color red
-fperez
-\color blue
-[
-\color cyan
-~/ipython
-\color blue
-]
-\color green
-2>
-\color none
- for i in (1,2,3):
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-
-\color green
-...>
-\color none
- \InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-print i,
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-
-\color green
-...>
-\color none
-
-\newline
-1 2 3
-\end_layout
-
-\begin_layout Standard
-The following shows the usage of dynamic expression evaluation:
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:profiles}
-
-\end_inset
-
-IPython profiles
-\end_layout
-
-\begin_layout Standard
-As we already mentioned, IPython supports the 
-\family typewriter
--profile
-\family default
- command-line option (see sec.
- 
-\begin_inset LatexCommand \ref{sec:cmd-line-opts}
-
-\end_inset
-
-).
- A profile is nothing more than a particular configuration file like your
- basic 
-\family typewriter
-ipythonrc
-\family default
- one, but with particular customizations for a specific purpose.
- When you start IPython with '
-\family typewriter
-ipython -profile <name>
-\family default
-', it assumes that in your 
-\family typewriter
-IPYTHONDIR
-\family default
- there is a file called 
-\family typewriter
-ipythonrc-<name>
-\family default
-, and loads it instead of the normal 
-\family typewriter
-ipythonrc
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-This system allows you to maintain multiple configurations which load modules,
- set options, define functions, etc.
- suitable for different tasks and activate them in a very simple manner.
- In order to avoid having to repeat all of your basic options (common things
- that don't change such as your color preferences, for example), any profile
- can include another configuration file.
- The most common way to use profiles is then to have each one include your
- basic 
-\family typewriter
-ipythonrc
-\family default
- file as a starting point, and then add further customizations.
-\end_layout
-
-\begin_layout Standard
-In sections 
-\begin_inset LatexCommand \ref{sec:syntax-extensions}
-
-\end_inset
-
- and 
-\begin_inset LatexCommand \ref{sec:Gnuplot}
-
-\end_inset
-
- we discuss some particular profiles which come as part of the standard
- IPython distribution.
- You may also look in your 
-\family typewriter
-IPYTHONDIR
-\family default
- directory, any file whose name begins with 
-\family typewriter
-ipythonrc-
-\family default
- is a profile.
- You can use those as examples for further customizations to suit your own
- needs.
-\end_layout
-
-\begin_layout Section
-\begin_inset OptArg
-status open
-
-\begin_layout Standard
-IPython as default...
-\end_layout
-
-\end_inset
-
-IPython as your default Python environment
-\end_layout
-
-\begin_layout Standard
-Python honors the environment variable 
-\family typewriter
-PYTHONSTARTUP 
-\family default
-and will execute at startup the file referenced by this variable.
- If you put at the end of this file the following two lines of code:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-import IPython
-\newline
-IPython.Shell.IPShell().mainloop(sys_exit=1)
-\end_layout
-
-\begin_layout Standard
-then IPython will be your working environment anytime you start Python.
- The 
-\family typewriter
-sys_exit=1
-\family default
- is needed to have IPython issue a call to 
-\family typewriter
-sys.exit()
-\family default
- when it finishes, otherwise you'll be back at the normal Python '
-\family typewriter
->>>
-\family default
-' prompt
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-Based on an idea by Holger Krekel.
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:embed}
-
-\end_inset
-
-Embedding IPython
-\end_layout
-
-\begin_layout Standard
-It is possible to start an IPython instance 
-\emph on
-inside
-\emph default
- 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
- 
-\emph on
-not
-\emph default
- 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.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-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
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-This functionality was inspired by IDL's combination of the 
-\family typewriter
-stop
-\family default
- keyword and the 
-\family typewriter
-.continue
-\family default
- executive command, which I have found very useful in the past, and by a
- posting on comp.lang.python by cmkl <cmkleffner-AT-gmx.de> on Dec.
- 06/01 concerning similar uses of pyrepl.
-\end_layout
-
-\end_inset
-
-.
- 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).
-\end_layout
-
-\begin_layout Standard
-The following code snippet is the bare minimum you need to include in your
- Python programs for this to work (detailed examples follow later):
-\end_layout
-
-\begin_layout LyX-Code
-from IPython.Shell import IPShellEmbed
-\end_layout
-
-\begin_layout LyX-Code
-ipshell = IPShellEmbed()
-\end_layout
-
-\begin_layout LyX-Code
-ipshell() # this call anywhere in your program will start IPython
-\end_layout
-
-\begin_layout Standard
-You can run embedded instances even in code which is itself being run at
- the IPython interactive prompt with '
-\family typewriter
-%run\InsetSpace ~
-<filename>
-\family default
-'.
- 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.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-Please look at the docstrings in the 
-\family typewriter
-Shell.py
-\family default
- module for more details on the use of this system.
-\end_layout
-
-\begin_layout Standard
-The following sample file illustrating how to use the embedding functionality
- is provided in the examples directory as 
-\family typewriter
-example-embed.py
-\family default
-.
- It should be fairly self-explanatory:
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-codelist{examples/example-embed.py}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Once you understand how the system functions, you can use the following
- code fragments in your programs which are ready for cut and paste:
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-codelist{examples/example-embed-short.py}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:using-pdb}
-
-\end_inset
-
-Using the Python debugger (
-\family typewriter
-pdb
-\family default
-)
-\end_layout
-
-\begin_layout Subsection
-Running entire programs via 
-\family typewriter
-pdb
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-pdb
-\family default
-, 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 
-\family typewriter
-pdb
-\family default
-, regardless of whether you have wrapped it into a 
-\family typewriter
-`main()'
-\family default
- function or not.
- For this, simply type 
-\family typewriter
-`%run -d myscript'
-\family default
- at an IPython prompt.
- See the 
-\family typewriter
-%run
-\family default
- command's documentation (via 
-\family typewriter
-`%run?'
-\family default
- or in Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
-) for more details, including how to control where 
-\family typewriter
-pdb
-\family default
- will stop execution first.
-\end_layout
-
-\begin_layout Standard
-For more information on the use of the 
-\family typewriter
-pdb
-\family default
- debugger, read the included 
-\family typewriter
-pdb.doc
-\family default
- file (part of the standard Python distribution).
- On a stock Linux system it is located at 
-\family typewriter
-/usr/lib/python2.3/pdb.doc
-\family default
-, but the easiest way to read it is by using the 
-\family typewriter
-help()
-\family default
- function of the 
-\family typewriter
-pdb
-\family default
- module as follows (in an IPython prompt):
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-In [1]: import pdb
-\newline
-In [2]: pdb.help()
-\end_layout
-
-\begin_layout Standard
-This will load the 
-\family typewriter
-pdb.doc
-\family default
- document in a file viewer for you automatically.
-\end_layout
-
-\begin_layout Subsection
-Automatic invocation of 
-\family typewriter
-pdb
-\family default
- on exceptions
-\end_layout
-
-\begin_layout Standard
-IPython, if started with the 
-\family typewriter
--pdb
-\family default
- option (or if the option is set in your rc file) can call the Python 
-\family typewriter
-pdb
-\family default
- debugger every time your code triggers an uncaught exception
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-Many thanks to Christopher Hart for the request which prompted adding this
- feature to IPython.
-\end_layout
-
-\end_inset
-
-.
- This feature can also be toggled at any time with the 
-\family typewriter
-%pdb
-\family default
- magic command.
- This can be extremely useful in order to find the origin of subtle bugs,
- because 
-\family typewriter
-pdb
-\family default
- 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.
-\end_layout
-
-\begin_layout Standard
-Furthermore, you can use these debugging facilities both with the embedded
- IPython mode and without IPython at all.
- For an embedded shell (see sec.
- 
-\begin_inset LatexCommand \ref{sec:embed}
-
-\end_inset
-
-), simply call the constructor with 
-\family typewriter
-`-pdb'
-\family default
- in the argument string and automatically 
-\family typewriter
-pdb
-\family default
- will be called if an uncaught exception is triggered by your code.
- 
-\end_layout
-
-\begin_layout Standard
-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:
-\end_layout
-
-\begin_layout Standard
-\align left
-
-\family typewriter
-import sys,IPython.ultraTB 
-\newline
-sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbos
-e', color_scheme=`Linux', call_pdb=1)
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-mode
-\family default
- keyword can be either 
-\family typewriter
-`Verbose'
-\family default
- or 
-\family typewriter
-`Plain'
-\family default
-, giving either very detailed or normal tracebacks respectively.
- The 
-\family typewriter
-color_scheme
-\family default
- keyword can be one of 
-\family typewriter
-`NoColor'
-\family default
-, 
-\family typewriter
-`Linux'
-\family default
- (default) or 
-\family typewriter
-`LightBG'
-\family default
-.
- These are the same options which can be set in IPython with 
-\family typewriter
--colors
-\family default
- and 
-\family typewriter
--xmode
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-This will give any of your programs detailed, colored tracebacks with automatic
- invocation of 
-\family typewriter
-pdb
-\family default
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:syntax-extensions}
-
-\end_inset
-
-Extensions for syntax processing
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-In the 
-\family typewriter
-IPython/Extensions
-\family default
- 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.
-\end_layout
-
-\begin_layout Subsection
-Pasting of code starting with 
-\family typewriter
-`>>> 
-\family default
-' or 
-\family typewriter
-`...
- 
-\family default
-'
-\end_layout
-
-\begin_layout Standard
-In the python tutorial it is common to find code examples which have been
- taken from real python sessions.
- The problem with those is that all the lines begin with either 
-\family typewriter
-`>>> 
-\family default
-' or 
-\family typewriter
-`...
- 
-\family default
-', which makes it impossible to paste them all at once.
- One must instead do a line by line manual copying, carefully removing the
- leading extraneous characters.
-\end_layout
-
-\begin_layout Standard
-This extension identifies those starting characters and removes them from
- the input automatically, so that one can paste multi-line examples directly
- into IPython, saving a lot of time.
- Please look at the file 
-\family typewriter
-InterpreterPasteInput.py
-\family default
- in the 
-\family typewriter
-IPython/Extensions
-\family default
- directory for details on how this is done.
-\end_layout
-
-\begin_layout Standard
-IPython comes with a special profile enabling this feature, called 
-\family typewriter
-tutorial
-\family default
-\emph on
-.
-
-\emph default
- Simply start IPython via 
-\family typewriter
-`ipython\InsetSpace ~
--p\InsetSpace ~
-tutorial'
-\family default
- and the feature will be available.
- In a normal IPython session you can activate the feature by importing the
- corresponding module with:
-\newline
-
-\family typewriter
-In [1]: import IPython.Extensions.InterpreterPasteInput
-\end_layout
-
-\begin_layout Standard
-The following is a 'screenshot' of how things work when this extension is
- on, copying an example from the standard tutorial:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-IPython profile: tutorial
-\newline
-\InsetSpace ~
-
-\newline
-*** Pasting of code with ">>>" or "..." has been enabled.
-\newline
-\InsetSpace ~
-
-\newline
-In
- [1]: >>> def fib2(n): # return Fibonacci series up to n
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- """Return a list containing the Fibonacci series up to n."""
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- result = []
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- a, b = 0, 1
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- while b < n:
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- result.append(b)\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- # see below
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- a, b = b, a+b
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...: ...\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
- return result
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
- ...:
-\newline
-\InsetSpace ~
-
-\newline
-In [2]: fib2(10)
-\newline
-Out[2]: [1, 1, 2, 3, 5, 8]
-\end_layout
-
-\begin_layout Standard
-Note that as currently written, this extension does 
-\emph on
-not 
-\emph default
-recognize IPython's prompts for pasting.
- Those are more complicated, since the user can change them very easily,
- they involve numbers and can vary in length.
- One could however extract all the relevant information from the IPython
- instance and build an appropriate regular expression.
- This is left as an exercise for the reader.
-\end_layout
-
-\begin_layout Subsection
-Input of physical quantities with units
-\end_layout
-
-\begin_layout Standard
-The module 
-\family typewriter
-PhysicalQInput
-\family default
- allows a simplified form of input for physical quantities with units.
- This file is meant to be used in conjunction with the 
-\family typewriter
-PhysicalQInteractive
-\family default
- module (in the same directory) and 
-\family typewriter
-Physics.PhysicalQuantities
-\family default
- from Konrad Hinsen's ScientificPython (
-\begin_inset LatexCommand \htmlurl{http://dirac.cnrs-orleans.fr/ScientificPython/}
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-Physics.PhysicalQuantities
-\family default
- module defines 
-\family typewriter
-PhysicalQuantity
-\family default
- objects, but these must be declared as instances of a class.
- For example, to define 
-\family typewriter
-v
-\family default
- as a velocity of 3\InsetSpace ~
-m/s, normally you would write:
-\family typewriter
-
-\newline
-In [1]: v = PhysicalQuantity(3,'m/s')
-\end_layout
-
-\begin_layout Standard
-Using the 
-\family typewriter
-PhysicalQ_Input
-\family default
- extension this can be input instead as:
-\family typewriter
-
-\newline
-In [1]: v = 3 m/s
-\family default
-
-\newline
-which is much more convenient for interactive use (even though it is blatantly
- invalid Python syntax).
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-physics
-\family default
- profile supplied with IPython (enabled via 
-\family typewriter
-'ipython -p physics'
-\family default
-) uses these extensions, which you can also activate with:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-from math import * # math MUST be imported BEFORE PhysicalQInteractive
-\newline
-from
- IPython.Extensions.PhysicalQInteractive import *
-\newline
-import IPython.Extensions.PhysicalQ
-Input
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:IPython-as-shell}
-
-\end_inset
-
-IPython as a system shell
-\end_layout
-
-\begin_layout Standard
-IPython ships with a special profile called 
-\family typewriter
-pysh
-\family default
-, which you can activate at the command line as 
-\family typewriter
-`ipython -p pysh'
-\family default
-.
- This loads 
-\family typewriter
-InterpreterExec
-\family default
-, along with some additional facilities and a prompt customized for filesystem
- navigation.
-\end_layout
-
-\begin_layout Standard
-Note that this does 
-\emph on
-not
-\emph default
- make IPython a full-fledged system shell.
- In particular, it has no job control, so if you type Ctrl-Z (under Unix),
- you'll suspend pysh itself, not the process you just started.
- 
-\end_layout
-
-\begin_layout Standard
-What the shell profile allows you to do is to use the convenient and powerful
- syntax of Python to do quick scripting at the command line.
- Below we describe some of its features.
-\end_layout
-
-\begin_layout Subsection
-Aliases
-\end_layout
-
-\begin_layout Standard
-All of your 
-\family typewriter
-$PATH
-\family default
- has been loaded as IPython aliases, so you should be able to type any normal
- system command and have it executed.
- See 
-\family typewriter
-%alias?
-\family default
- and 
-\family typewriter
-%unalias?
-\family default
- for details on the alias facilities.
- See also 
-\family typewriter
-%rehash?
-\family default
- and 
-\family typewriter
-%rehashx? 
-\family default
-for details on the mechanism used to load 
-\family typewriter
-$PATH
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Special syntax
-\end_layout
-
-\begin_layout Standard
-Any lines which begin with 
-\family typewriter
-`~'
-\family default
-, 
-\family typewriter
-`/'
-\family default
- and 
-\family typewriter
-`.'
-\family default
- will be executed as shell commands instead of as Python code.
- The special escapes below are also recognized.
- 
-\family typewriter
-!cmd
-\family default
- is valid in single or multi-line input, all others are only valid in single-lin
-e input:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-!cmd
-\family default
- pass `cmd' directly to the shell 
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-!!cmd
-\family default
- execute `cmd' and return output as a list (split on `
-\backslash
-n') 
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-$var=cmd
-\family default
- capture output of cmd into var, as a string 
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-$$var=cmd
-\family default
- capture output of cmd into var, as a list (split on `
-\backslash
-n')
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-$
-\family default
-/
-\family typewriter
-$$
-\family default
- syntaxes make Python variables from system output, which you can later
- use for further scripting.
- The converse is also possible: when executing an alias or calling to the
- system via 
-\family typewriter
-!
-\family default
-/
-\family typewriter
-!!
-\family default
-, you can expand any python variable or expression by prepending it with
- 
-\family typewriter
-$
-\family default
-.
- Full details of the allowed syntax can be found in Python's PEP 215.
-\end_layout
-
-\begin_layout Standard
-A few brief examples will illustrate these (note that the indentation below
- may be incorrectly displayed):
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|3> !ls *s.py 
-\newline
-scopes.py strings.py
-\end_layout
-
-\begin_layout Standard
-ls is an internal alias, so there's no need to use 
-\family typewriter
-!
-\family default
-: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|4> ls *s.py 
-\newline
-scopes.py* strings.py
-\end_layout
-
-\begin_layout Standard
-!!ls will return the output into a Python variable: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|5> !!ls *s.py 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-<5> ['scopes.py', 'strings.py'] 
-\newline
-fperez[~/test]|6> print _5 
-\newline
-['scopes.py', 'strings.py
-']
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-$
-\family default
- and 
-\family typewriter
-$$
-\family default
- allow direct capture to named variables: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|7> $astr = ls *s.py 
-\newline
-fperez[~/test]|8> astr 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-<8> 'scopes.py
-\backslash
-nstrings.py'
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|9> $$alist = ls *s.py 
-\newline
-fperez[~/test]|10> alist 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-<10> ['scopes.py', 'strings.py']
-\end_layout
-
-\begin_layout Standard
-alist is now a normal python list you can loop over.
- Using 
-\family typewriter
-$
-\family default
- will expand back the python values when alias calls are made:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|11> for f in alist: 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-|..> \InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-print 'file',f, 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-|..> \InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-wc -l $f 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-|..> 
-\newline
-file scopes.py 13 scopes.py 
-\newline
-file strings.py 4 strings.py
-\end_layout
-
-\begin_layout Standard
-Note that you may need to protect your variables with braces if you want
- to append strings to their names.
- To copy all files in alist to 
-\family typewriter
-.bak
-\family default
- extensions, you must use: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|12> for f in alist: 
-\newline
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-hspace*{0mm}
-\end_layout
-
-\end_inset
-
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-|..> \InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-cp $f ${f}.bak
-\end_layout
-
-\begin_layout Standard
-If you try using 
-\family typewriter
-$f.bak
-\family default
-, you'll get an AttributeError exception saying that your string object
- doesn't have a 
-\family typewriter
-.bak
-\family default
- attribute.
- This is because the 
-\family typewriter
-$
-\family default
- expansion mechanism allows you to expand full Python expressions: 
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-fperez[~/test]|13> echo "sys.platform is: $sys.platform" 
-\newline
-sys.platform is: linux2
-\end_layout
-
-\begin_layout Standard
-IPython's input history handling is still active, which allows you to rerun
- a single block of multi-line input by simply using exec: 
-\newline
-
-\family typewriter
-fperez[~/test]|14> $$alist = ls *.eps 
-\newline
-fperez[~/test]|15> exec _i11 
-\newline
-file image2.eps
- 921 image2.eps 
-\newline
-file image.eps 921 image.eps
-\end_layout
-
-\begin_layout Standard
-While these are new special-case syntaxes, they are designed to allow very
- efficient use of the shell with minimal typing.
- At an interactive shell prompt, conciseness of expression wins over readability.
-\end_layout
-
-\begin_layout Subsection
-Useful functions and modules
-\end_layout
-
-\begin_layout Standard
-The os, sys and shutil modules from the Python standard library are automaticall
-y loaded.
- Some additional functions, useful for shell usage, are listed below.
- You can request more help about them with `
-\family typewriter
-?
-\family default
-'.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-shell
-\family default
- - execute a command in the underlying system shell 
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-system
-\family default
- - like 
-\family typewriter
-shell()
-\family default
-, but return the exit status of the command
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-sout
-\family default
- - capture the output of a command as a string
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-lout
-\family default
- - capture the output of a command as a list (split on `
-\backslash
-n')
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-getoutputerror
-\family default
- - capture (output,error) of a shell commandss
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-sout
-\family default
-/
-\family typewriter
-lout
-\family default
- are the functional equivalents of 
-\family typewriter
-$
-\family default
-/
-\family typewriter
-$$
-\family default
-.
- They are provided to allow you to capture system output in the middle of
- true python code, function definitions, etc (where 
-\family typewriter
-$
-\family default
- and 
-\family typewriter
-$$
-\family default
- are invalid).
-\end_layout
-
-\begin_layout Subsection
-Directory management
-\end_layout
-
-\begin_layout Standard
-Since each command passed by pysh to the underlying system is executed in
- a subshell which exits immediately, you can NOT use !cd to navigate the
- filesystem.
-\end_layout
-
-\begin_layout Standard
-Pysh provides its own builtin 
-\family typewriter
-`%cd
-\family default
-' magic command to move in the filesystem (the 
-\family typewriter
-%
-\family default
- is not required with automagic on).
- It also maintains a list of visited directories (use 
-\family typewriter
-%dhist
-\family default
- to see it) and allows direct switching to any of them.
- Type 
-\family typewriter
-`cd?
-\family default
-' for more details.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-%pushd
-\family default
-, 
-\family typewriter
-%popd
-\family default
- and 
-\family typewriter
-%dirs
-\family default
- are provided for directory stack handling.
-\end_layout
-
-\begin_layout Subsection
-Prompt customization
-\end_layout
-
-\begin_layout Standard
-The supplied 
-\family typewriter
-ipythonrc-pysh
-\family default
- profile comes with an example of a very colored and detailed prompt, mainly
- to serve as an illustration.
- The valid escape sequences, besides color names, are:
-\end_layout
-
-\begin_layout Description
-
-\backslash
-# - Prompt number, wrapped in the color escapes for the input prompt (determined
- by the current color scheme).
-\end_layout
-
-\begin_layout Description
-
-\backslash
-N - Just the prompt counter number, 
-\emph on
-without
-\emph default
- any coloring wrappers.
- You can thus customize the actual prompt colors manually.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-D - Dots, as many as there are digits in 
-\backslash
-# (so they align).
-\end_layout
-
-\begin_layout Description
-
-\backslash
-w - Current working directory (cwd).
-\end_layout
-
-\begin_layout Description
-
-\backslash
-W - Basename of current working directory.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-X
-\emph on
-N
-\emph default
- - Where 
-\emph on
-N
-\emph default
-=0..5.
- N terms of the cwd, with $HOME written as ~.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-Y
-\emph on
-N
-\emph default
- - Where 
-\emph on
-N
-\emph default
-=0..5.
- Like X
-\emph on
-N
-\emph default
-, but if ~ is term 
-\emph on
-N
-\emph default
-+1 it's also shown.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-u - Username.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-H - Full hostname.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-h - Hostname up to first '.'
-\end_layout
-
-\begin_layout Description
-
-\backslash
-$ - Root symbol ($ or #).
- 
-\end_layout
-
-\begin_layout Description
-
-\backslash
-t - Current time, in H:M:S format.
-\end_layout
-
-\begin_layout Description
-
-\backslash
-v - IPython release version.
- 
-\end_layout
-
-\begin_layout Description
-
-\backslash
-n - Newline.
- 
-\end_layout
-
-\begin_layout Description
-
-\backslash
-r - Carriage return.
- 
-\end_layout
-
-\begin_layout Description
-
-\backslash
-
-\backslash
- - An explicitly escaped '
-\backslash
-'.
-\end_layout
-
-\begin_layout Standard
-You can configure your prompt colors using any ANSI color escape.
- Each color escape sets the color for any subsequent text, until another
- escape comes in and changes things.
- The valid color escapes are:
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Black
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Blue
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Brown
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Cyan
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_DarkGray
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Green
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightBlue
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightCyan
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightGray
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightGreen
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightPurple
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_LightRed
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Purple
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Red
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_White
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Yellow
-\end_layout
-
-\begin_layout Description
-
-\backslash
-C_Normal Stop coloring, defaults to your terminal settings.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Threading-support}
-
-\end_inset
-
-Threading support
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-WARNING: 
-\series default
-The threading support is still somewhat experimental, and it has only seen
- reasonable testing under Linux.
- Threaded code is particularly tricky to debug, and it tends to show extremely
- platform-dependent behavior.
- Since I only have access to Linux machines, I will have to rely on user's
- experiences and assistance for this area of IPython to improve under other
- platforms.
-\end_layout
-
-\begin_layout Standard
-IPython, via the 
-\family typewriter
--gthread
-\family default
- , 
-\family typewriter
--qthread
-\family default
-, 
-\family typewriter
--q4thread
-\family default
- and 
-\family typewriter
--wthread
-\family default
- options (described in Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:threading-opts}
-
-\end_inset
-
-), can run in multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython
- applications respectively.
- These GUI toolkits need to control the python main loop of execution, so
- under a normal Python interpreter, starting a pyGTK, Qt3, Qt4 or WXPython
- application will immediately freeze the shell.
- 
-\end_layout
-
-\begin_layout Standard
-IPython, with one of these options (you can only use one at a time), separates
- the graphical loop and IPython's code execution run into different threads.
- This allows you to test interactively (with 
-\family typewriter
-%run
-\family default
-, for example) your GUI code without blocking.
-\end_layout
-
-\begin_layout Standard
-A nice mini-tutorial on using IPython along with the Qt Designer application
- is available at the SciPy wiki: 
-\begin_inset LatexCommand \htmlurl{http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Tk issues
-\end_layout
-
-\begin_layout Standard
-As indicated in Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:threading-opts}
-
-\end_inset
-
-, a special 
-\family typewriter
--tk
-\family default
- option is provided to try and allow Tk graphical applications to coexist
- interactively with WX, Qt or GTK ones.
- Whether this works at all, however, is very platform and configuration
- dependent.
- Please experiment with simple test cases before committing to using this
- combination of Tk and GTK/Qt/WX threading in a production environment.
-\end_layout
-
-\begin_layout Subsection
-I/O pitfalls
-\end_layout
-
-\begin_layout Standard
-Be mindful that the Python interpreter switches between threads every 
-\begin_inset Formula $N$
-\end_inset
-
- bytecodes, where the default value as of Python\InsetSpace ~
-2.3 is 
-\begin_inset Formula $N=100.$
-\end_inset
-
- This value can be read by using the 
-\family typewriter
-sys.getcheckinterval()
-\family default
- function, and it can be reset via 
-\family typewriter
-sys.setcheckinterval(
-\emph on
-N
-\emph default
-)
-\family default
-.
- This switching of threads can cause subtly confusing effects if one of
- your threads is doing file I/O.
- In text mode, most systems only flush file buffers when they encounter
- a 
-\family typewriter
-`
-\backslash
-n'
-\family default
-.
- An instruction as simple as
-\family typewriter
-
-\newline
-\InsetSpace ~
-\InsetSpace ~
-print >> filehandle, 
-\begin_inset Quotes eld
-\end_inset
-
-hello world
-\begin_inset Quotes erd
-\end_inset
-
-
-\family default
-
-\newline
-actually consists of several bytecodes, so it is possible that the newline
- does not reach your file before the next thread switch.
- Similarly, if you are writing to a file in binary mode, the file won't
- be flushed until the buffer fills, and your other thread may see apparently
- truncated files.
- 
-\end_layout
-
-\begin_layout Standard
-For this reason, if you are using IPython's thread support and have (for
- example) a GUI application which will read data generated by files written
- to from the IPython thread, the safest approach is to open all of your
- files in unbuffered mode (the third argument to the 
-\family typewriter
-file/open
-\family default
- function is the buffering value):
-\newline
-
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-filehandle = open(filename,mode,0)
-\end_layout
-
-\begin_layout Standard
-This is obviously a brute force way of avoiding race conditions with the
- file buffering.
- If you want to do it cleanly, and you have a resource which is being shared
- by the interactive IPython loop and your GUI thread, you should really
- handle it with thread locking and syncrhonization properties.
- The Python documentation discusses these.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:interactive-demos}
-
-\end_inset
-
-Interactive demos with IPython
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-codelist{examples/example-demo.py}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-In order to run a file as a demo, you must first make a 
-\family typewriter
-Demo
-\family default
- object out of it.
- If the file is named 
-\family typewriter
-myscript.py
-\family default
-, the following code will make a demo:
-\end_layout
-
-\begin_layout LyX-Code
-from IPython.demo import Demo
-\end_layout
-
-\begin_layout LyX-Code
-mydemo = Demo('myscript.py')
-\end_layout
-
-\begin_layout Standard
-This creates the 
-\family typewriter
-mydemo
-\family default
- 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
-\end_layout
-
-\begin_layout LyX-Code
-mydemo
-\end_layout
-
-\begin_layout Standard
-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 
-\family typewriter
-`?'
-\family default
- on them to see their docstrings for more usage details.
- In addition, the 
-\family typewriter
-demo
-\family default
- module itself contains a comprehensive docstring, which you can access
- via
-\end_layout
-
-\begin_layout LyX-Code
-from IPython import demo
-\end_layout
-
-\begin_layout LyX-Code
-demo?
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-Limitations:
-\series default
- It is important to note that these demos are limited to fairly simple uses.
- In particular, you can 
-\emph on
-not
-\emph default
- put division marks in indented code (loops, if statements, function definitions
-, etc.) Supporting something like this would basically require tracking the
- internal execution state of the Python interpreter, so only top-level divisions
- are allowed.
- If you want to be able to open an IPython instance at an arbitrary point
- in a program, you can use IPython's embedding facilities, described in
- detail in Sec\SpecialChar \@.
-\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:embed}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:matplotlib-support}
-
-\end_inset
-
-Plotting with 
-\family typewriter
-matplotlib
-\family default
- 
-\end_layout
-
-\begin_layout Standard
-The matplotlib library (
-\begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
-
-\end_inset
-
-) provides high quality 2D plotting for Python.
- Matplotlib can produce plots on screen using a variety of GUI toolkits,
- including Tk, GTK and WXPython.
- It also provides a number of commands useful for scientific computing,
- all with a syntax compatible with that of the popular Matlab program.
-\end_layout
-
-\begin_layout Standard
-IPython accepts the special option 
-\family typewriter
--pylab
-\family default
- (Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:cmd-line-opts}
-
-\end_inset
-
-).
- This configures it to support matplotlib, honoring the settings in the
- 
-\family typewriter
-.matplotlibrc
-\family default
- file.
- IPython will detect the user's choice of matplotlib GUI backend, and automatica
-lly select the proper threading model to prevent blocking.
- It also sets matplotlib in interactive mode and modifies 
-\family typewriter
-%run
-\family default
- slightly, so that any matplotlib-based script can be executed using 
-\family typewriter
-%run
-\family default
- and the final 
-\family typewriter
-show()
-\family default
- command does not block the interactive shell.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
--pylab
-\family default
- option must be given first in order for IPython to configure its threading
- mode.
- However, you can still issue other options afterwards.
- This allows you to have a matplotlib-based environment customized with
- additional modules using the standard IPython profile mechanism (Sec.\InsetSpace ~
-
-\begin_inset LatexCommand \ref{sec:profiles}
-
-\end_inset
-
-): ``
-\family typewriter
-ipython -pylab -p myprofile
-\family default
-'' will load the profile defined in 
-\family typewriter
-ipythonrc-myprofile
-\family default
- after configuring matplotlib.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Gnuplot}
-
-\end_inset
-
-Plotting with 
-\family typewriter
-Gnuplot
-\end_layout
-
-\begin_layout Standard
-Through the magic extension system described in sec.
- 
-\begin_inset LatexCommand \ref{sec:magic}
-
-\end_inset
-
-, IPython incorporates a mechanism for conveniently interfacing with the
- Gnuplot system (
-\begin_inset LatexCommand \htmlurl{http://www.gnuplot.info}
-
-\end_inset
-
-).
- Gnuplot is a very complete 2D and 3D plotting package available for many
- operating systems and commonly included in modern Linux distributions.
- 
-\end_layout
-
-\begin_layout Standard
-Besides having Gnuplot installed, this functionality requires the 
-\family typewriter
-Gnuplot.py
-\family default
- module for interfacing python with Gnuplot.
- It can be downloaded from: 
-\begin_inset LatexCommand \htmlurl{http://gnuplot-py.sourceforge.net}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Proper Gnuplot configuration
-\end_layout
-
-\begin_layout Standard
-As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support.
- However, as of 
-\family typewriter
-Gnuplot.py
-\family default
- version 1.7, a new option was added to communicate between Python and Gnuplot
- via FIFOs (pipes).
- This mechanism, while fast, also breaks the mouse system.
- You must therefore set the variable 
-\family typewriter
-prefer_fifo_data
-\family default
- to 
-\family typewriter
-0
-\family default
- in file 
-\family typewriter
-gp_unix.py
-\family default
- if you wish to keep the interactive mouse and keyboard features working
- properly (
-\family typewriter
-prefer_inline_data
-\family default
- also must be 
-\family typewriter
-0
-\family default
-, but this is the default so unless you've changed it manually you should
- be fine).
-\end_layout
-
-\begin_layout Standard
-'Out of the box', Gnuplot is configured with a rather poor set of size,
- color and linewidth choices which make the graphs fairly hard to read on
- modern high-resolution displays (although they work fine on old 640x480
- ones).
- Below is a section of my 
-\family typewriter
-.Xdefaults
-\family default
- file which I use for having a more convenient Gnuplot setup.
- Remember to load it by running 
-\family typewriter
-`xrdb .Xdefaults`
-\family default
-:
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-!******************************************************************
-\newline
-! gnuplot
- options
-\newline
-! modify this for a convenient window size
-\newline
-gnuplot*geometry: 780x580
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-! on-screen font (not for PostScript)
-\newline
-gnuplot*font: -misc-fixed-bold-r-normal--15
--120-100-100-c-90-iso8859-1
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-! color options
-\newline
-gnuplot*background: black
-\newline
-gnuplot*textColor: white
-\newline
-gnuplot*borderCo
-lor: white
-\newline
-gnuplot*axisColor: white
-\newline
-gnuplot*line1Color: red
-\newline
-gnuplot*line2Color:
- green
-\newline
-gnuplot*line3Color: blue
-\newline
-gnuplot*line4Color: magenta
-\newline
-gnuplot*line5Color:
- cyan
-\newline
-gnuplot*line6Color: sienna
-\newline
-gnuplot*line7Color: orange
-\newline
-gnuplot*line8Color:
- coral
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-! multiplicative factor for point styles
-\newline
-gnuplot*pointsize: 2
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-! line width options (in pixels)
-\newline
-gnuplot*borderWidth: 2
-\newline
-gnuplot*axisWidth:
- 2
-\newline
-gnuplot*line1Width: 2
-\newline
-gnuplot*line2Width: 2
-\newline
-gnuplot*line3Width: 2
-\newline
-gnuplot*line4Wi
-dth: 2
-\newline
-gnuplot*line5Width: 2
-\newline
-gnuplot*line6Width: 2
-\newline
-gnuplot*line7Width: 2
-\newline
-gnuplot*lin
-e8Width: 2
-\end_layout
-
-\begin_layout Subsection
-The 
-\family typewriter
-IPython.GnuplotRuntime
-\family default
- module
-\end_layout
-
-\begin_layout Standard
-IPython includes a module called 
-\family typewriter
-Gnuplot2.py
-\family default
- which extends and improves the default 
-\family typewriter
-Gnuplot
-\family default
-.
-\family typewriter
-py
-\family default
- (which it still relies upon).
- For example, the new 
-\family typewriter
-plot
-\family default
- function adds several improvements to the original making it more convenient
- for interactive use, and 
-\family typewriter
-hardcopy
-\family default
- fixes a bug in the original which under some circumstances blocks the creation
- of PostScript output.
-\end_layout
-
-\begin_layout Standard
-For scripting use, 
-\family typewriter
-GnuplotRuntime.py
-\family default
- is provided, which wraps 
-\family typewriter
-Gnuplot2.py
-\family default
- and creates a series of global aliases.
- These make it easy to control Gnuplot plotting jobs through the Python
- language.
-\end_layout
-
-\begin_layout Standard
-Below is some example code which illustrates how to configure Gnuplot inside
- your own programs but have it available for further interactive use through
- an embedded IPython instance.
- Simply run this file at a system prompt.
- This file is provided as 
-\family typewriter
-example-gnuplot.py
-\family default
- in the examples directory:
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-codelist{examples/example-gnuplot.py}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-The 
-\family typewriter
-numeric
-\family default
- profile: a scientific computing environment
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-numeric
-\family default
- IPython profile, which you can activate with 
-\family typewriter
-`ipython -p numeric
-\family default
-' will automatically load the IPython Gnuplot extensions (plus Numeric and
- other useful things for numerical computing), contained in the 
-\family typewriter
-IPython.GnuplotInteractive
-\family default
- module.
- This will create the globals 
-\family typewriter
-Gnuplot 
-\family default
-(an alias to the improved Gnuplot2 module), 
-\family typewriter
-gp
-\family default
- (a Gnuplot active instance), the new magic commands 
-\family typewriter
-%gpc
-\family default
- and 
-\family typewriter
-%gp_set_instance
-\family default
- and several other convenient globals.
- Type 
-\family typewriter
-gphelp()
-\family default
- for further details.
-\end_layout
-
-\begin_layout Standard
-This should turn IPython into a convenient environment for numerical computing,
- with all the functions in the NumPy library and the Gnuplot facilities
- for plotting.
- Further improvements can be obtained by loading the SciPy libraries for
- scientific computing, available at 
-\begin_inset LatexCommand \htmlurl{http://scipy.org}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-If you are in the middle of a working session with numerical objects and
- need to plot them but you didn't start the 
-\family typewriter
-numeric
-\family default
- profile, you can load these extensions at any time by typing
-\newline
-
-\family typewriter
-from IPython.GnuplotInteractive import *
-\newline
-
-\family default
-at the IPython prompt.
- This will allow you to keep your objects intact and start using Gnuplot
- to view them.
-\end_layout
-
-\begin_layout Section
-Reporting bugs
-\end_layout
-
-\begin_layout Subsection*
-Automatic crash reports
-\end_layout
-
-\begin_layout Standard
-Ideally, IPython itself shouldn't crash.
- It will catch exceptions produced by you, but bugs in its internals will
- still crash it.
-\end_layout
-
-\begin_layout Standard
-In such a situation, IPython will leave a file named 
-\family typewriter
-IPython_crash_report.txt
-\family default
- in your IPYTHONDIR directory (that way if crashes happen several times
- it won't litter many directories, the post-mortem file is always located
- in the same place and new occurrences just overwrite the previous one).
- If you can mail this file to the developers (see sec.
- 
-\begin_inset LatexCommand \ref{sec:credits}
-
-\end_inset
-
- for names and addresses), it will help us 
-\emph on
-a lot
-\emph default
- in understanding the cause of the problem and fixing it sooner.
-\end_layout
-
-\begin_layout Subsection*
-The bug tracker
-\end_layout
-
-\begin_layout Standard
-IPython also has an online bug-tracker, located at 
-\begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/report/1}
-
-\end_inset
-
-.
- In addition to mailing the developers, it would be a good idea to file
- a bug report here.
- This will ensure that the issue is properly followed to conclusion.
- To report new bugs you will have to register first.
-\end_layout
-
-\begin_layout Standard
-You can also use this bug tracker to file feature requests.
-\end_layout
-
-\begin_layout Section
-Brief history
-\end_layout
-
-\begin_layout Subsection
-Origins
-\end_layout
-
-\begin_layout Standard
-The current IPython system grew out of the following three projects:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-ipython by Fernando P
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-'{e}
-\end_layout
-
-\end_inset
-
-rez.
- I was working on adding Mathematica-type prompts and a flexible configuration
- system (something better than 
-\family typewriter
-$PYTHONSTARTUP
-\family default
-) to the standard Python interactive interpreter.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-IPP by Janko Hauser.
- Very well organized, great usability.
- Had an old help system.
- IPP was used as the `container' code into which I added the functionality
- from ipython and LazyPython.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-LazyPython by Nathan Gray.
- Simple but 
-\emph on
-very
-\emph default
- powerful.
- The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks
- were all taken from here.
-\end_layout
-
-\begin_layout Standard
-When I found out (see sec.
- 
-\begin_inset LatexCommand \ref{figgins}
-
-\end_inset
-
-) about IPP and LazyPython I tried to join all three into a unified system.
- I thought this could provide a very nice working environment, both for
- regular programming and scientific computing: shell-like features, IDL/Matlab
- numerics, Mathematica-type prompt history and great object introspection
- and help facilities.
- I think it worked reasonably well, though it was a lot more work than I
- had initially planned.
-\end_layout
-
-\begin_layout Subsection
-Current status
-\end_layout
-
-\begin_layout Standard
-The above listed features work, and quite well for the most part.
- But until a major internal restructuring is done (see below), only bug
- fixing will be done, no other features will be added (unless very minor
- and well localized in the cleaner parts of the code).
-\end_layout
-
-\begin_layout Standard
-IPython consists of some 18000 lines of pure python code, of which roughly
- two thirds is reasonably clean.
- The rest is, messy code which needs a massive restructuring before any
- further major work is done.
- Even the messy code is fairly well documented though, and most of the problems
- in the (non-existent) class design are well pointed to by a PyChecker run.
- So the rewriting work isn't that bad, it will just be time-consuming.
-\end_layout
-
-\begin_layout Subsection
-Future
-\end_layout
-
-\begin_layout Standard
-See the separate 
-\family typewriter
-new_design
-\family default
- document for details.
- Ultimately, I would like to see IPython become part of the standard Python
- distribution as a `big brother with batteries' to the standard Python interacti
-ve interpreter.
- But that will never happen with the current state of the code, so all contribut
-ions are welcome.
-\end_layout
-
-\begin_layout Section
-License
-\end_layout
-
-\begin_layout Standard
-IPython is released under the terms of the BSD license, whose general form
- can be found at: 
-\begin_inset LatexCommand \htmlurl{http://www.opensource.org/licenses/bsd-license.php}
-
-\end_inset
-
-.
- The full text of the IPython license is reproduced below:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-IPython is released under a BSD-type license.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez <[e-mail]>.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-Copyright (c) 2001 Janko Hauser <[e-mail]> and 
-\newline
-Nathaniel Gray <n8gray@ca
-ltech.edu>.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-All rights reserved.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-Redistribution and use in source and binary forms, with or without modification,
- are permitted provided that the following conditions are met:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-a.
- Redistributions of source code must retain the above copyright notice,
- this list of conditions and the following disclaimer.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-b.
- Redistributions in binary form must reproduce the above copyright notice,
- this list of conditions and the following disclaimer in the documentation
- and/or other materials provided with the distribution.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-c.
- Neither the name of the copyright holders nor the names of any contributors
- to this software may be used to endorse or promote products derived from
- this software without specific prior written permission.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
- IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
- THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE ARE DISCLAIMED.
- IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
- BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
- ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- 
-\end_layout
-
-\begin_layout Standard
-Individual authors are the holders of the copyright for their code and are
- listed in each file.
-\end_layout
-
-\begin_layout Standard
-Some files (
-\family typewriter
-DPyGetOpt.py
-\family default
-, for example) may be licensed under different conditions.
- Ultimately each file indicates clearly the conditions under which its author/au
-thors have decided to publish the code.
-\end_layout
-
-\begin_layout Standard
-Versions of IPython up to and including 0.6.3 were released under the GNU
- Lesser General Public License (LGPL), available at 
-\begin_inset LatexCommand \htmlurl{http://www.gnu.org/copyleft/lesser.html}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:credits}
-
-\end_inset
-
-Credits
-\end_layout
-
-\begin_layout Standard
-IPython is mainly developed by Fernando P
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-'{e}
-\end_layout
-
-\end_inset
-
-rez 
-\family typewriter
-<[e-mail]>
-\family default
-, but the project was born from mixing in Fernando's code with the IPP project
- by Janko Hauser 
-\family typewriter
-<jhauser-AT-zscout.de>
-\family default
- and LazyPython by Nathan Gray 
-\family typewriter
-<n8gray-AT-caltech.edu>
-\family default
-.
- For all IPython-related requests, please contact Fernando.
- 
-\end_layout
-
-\begin_layout Standard
-As of early 2006, the following developers have joined the core team:
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Robert\InsetSpace ~
-Kern 
-\family typewriter
-<rkern-AT-enthought.com>
-\family default
-: co-mentored the 2005 Google Summer of Code project to develop python interacti
-ve notebooks (XML documents) and graphical interface.
- This project was awarded to the students Tzanko Matev 
-\family typewriter
-<tsanko-AT-gmail.com>
-\family default
- and Toni Alatalo 
-\family typewriter
-<antont-AT-an.org>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Brian\InsetSpace ~
-Granger 
-\family typewriter
-<bgranger-AT-scu.edu>
-\family default
-: extending IPython to allow support for interactive parallel computing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Ville\InsetSpace ~
-Vainio 
-\family typewriter
-<vivainio-AT-gmail.com>
-\family default
-: Ville is the new maintainer for the main trunk of IPython after version
- 0.7.1.
-\end_layout
-
-\begin_layout Standard
-User or development help should be requested via the IPython mailing lists:
-\end_layout
-
-\begin_layout Description
-User\InsetSpace ~
-list: 
-\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-Developer's\InsetSpace ~
-list: 
-\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The IPython project is also very grateful to
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-I've mangled email addresses to reduce spam, since the IPython manuals can
- be accessed online.
-\end_layout
-
-\end_inset
-
-:
-\end_layout
-
-\begin_layout Standard
-Bill Bumgarner 
-\family typewriter
-<bbum-AT-friday.com>
-\family default
-: for providing the DPyGetOpt module which gives very powerful and convenient
- handling of command-line options (light years ahead of what Python 2.1.1's
- getopt module does).
-\end_layout
-
-\begin_layout Standard
-Ka-Ping Yee 
-\family typewriter
-<ping-AT-lfw.org>
-\family default
-: for providing the Itpl module for convenient and powerful string interpolation
- with a much nicer syntax than formatting through the '%' operator.
-\end_layout
-
-\begin_layout Standard
-Arnd Baecker 
-\family typewriter
-<baecker-AT-physik.tu-dresden.de>
-\family default
-: for his many very useful suggestions and comments, and lots of help with
- testing and documentation checking.
- Many of IPython's newer features are a result of discussions with him (bugs
- are still my fault, not his).
-\end_layout
-
-\begin_layout Standard
-Obviously Guido van\InsetSpace ~
-Rossum and the whole Python development team, that goes
- without saying.
-\end_layout
-
-\begin_layout Standard
-IPython's website is generously hosted at 
-\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
-
-\end_inset
-
- by Enthought (
-\begin_inset LatexCommand \htmlurl{http://www.enthought.com}
-
-\end_inset
-
-).
- I am very grateful to them and all of the SciPy team for their contribution.
-\end_layout
-
-\begin_layout Standard
-\begin_inset LatexCommand \label{figgins}
-
-\end_inset
-
-Fernando would also like to thank Stephen Figgins 
-\family typewriter
-<fig-AT-monitor.net>
-\family default
-, an O'Reilly Python editor.
- His Oct/11/2001 article about IPP and LazyPython, was what got this project
- started.
- You can read it at: 
-\begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-And last but not least, all the kind IPython users who have emailed new
- code, bug reports, fixes, comments and ideas.
- A brief list follows, please let me know if I have ommitted your name by
- accident: 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Jack\InsetSpace ~
-Moffit 
-\family typewriter
-<jack-AT-xiph.org>
-\family default
- Bug fixes, including the infamous color problem.
- This bug alone caused many lost hours and frustration, many thanks to him
- for the fix.
- I've always been a fan of Ogg & friends, now I have one more reason to
- like these folks.
-\newline
-Jack is also contributing with Debian packaging and many
- other things.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Alexander\InsetSpace ~
-Schmolck 
-\family typewriter
-<a.schmolck-AT-gmx.net> 
-\family default
-Emacs work, bug reports, bug fixes, ideas, lots more.
- The ipython.el mode for (X)Emacs is Alex's code, providing full support
- for IPython under (X)Emacs.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Andrea\InsetSpace ~
-Riciputi 
-\family typewriter
-<andrea.riciputi-AT-libero.it>
-\family default
- Mac OSX information, Fink package management.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gary\InsetSpace ~
-Bishop 
-\family typewriter
-<gb-AT-cs.unc.edu>
-\family default
- Bug reports, and patches to work around the exception handling idiosyncracies
- of WxPython.
- Readline and color support for Windows.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Jeffrey\InsetSpace ~
-Collins 
-\family typewriter
-<Jeff.Collins-AT-vexcel.com>
-\family default
- Bug reports.
- Much improved readline support, including fixes for Python 2.3.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Dryice\InsetSpace ~
-Liu 
-\family typewriter
-<dryice-AT-liu.com.cn>
-\family default
- FreeBSD port.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Mike\InsetSpace ~
-Heeter 
-\family typewriter
-<korora-AT-SDF.LONESTAR.ORG>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Christopher\InsetSpace ~
-Hart 
-\family typewriter
-<hart-AT-caltech.edu>
-\family default
- PDB integration.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Milan\InsetSpace ~
-Zamazal 
-\family typewriter
-<pdm-AT-zamazal.org>
-\family default
- Emacs info.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Philip\InsetSpace ~
-Hisley 
-\family typewriter
-<compsys-AT-starpower.net>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Holger\InsetSpace ~
-Krekel 
-\family typewriter
-<pyth-AT-devel.trillke.net>
-\family default
- Tab completion, lots more.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Robin\InsetSpace ~
-Siebler 
-\family typewriter
-<robinsiebler-AT-starband.net>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Ralf\InsetSpace ~
-Ahlbrink
-\family typewriter
- <ralf_ahlbrink-AT-web.de>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Thorsten\InsetSpace ~
-Kampe 
-\family typewriter
-<thorsten-AT-thorstenkampe.de>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Fredrik\InsetSpace ~
-Kant 
-\family typewriter
-<fredrik.kant-AT-front.com>
-\family default
- Windows setup.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Syver\InsetSpace ~
-Enstad 
-\family typewriter
-<syver-en-AT-online.no>
-\family default
- Windows setup.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Richard 
-\family typewriter
-<rxe-AT-renre-europe.com>
-\family default
- Global embedding.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Hayden\InsetSpace ~
-Callow 
-\family typewriter
-<h.callow-AT-elec.canterbury.ac.nz>
-\family default
- Gnuplot.py 1.6 compatibility.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Leonardo\InsetSpace ~
-Santagada 
-\family typewriter
-<retype-AT-terra.com.br>
-\family default
- Fixes for Windows installation.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Christopher\InsetSpace ~
-Armstrong 
-\family typewriter
-<radix-AT-twistedmatrix.com>
-\family default
- Bugfixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Francois\InsetSpace ~
-Pinard 
-\family typewriter
-<pinard-AT-iro.umontreal.ca>
-\family default
- Code and documentation fixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Cory\InsetSpace ~
-Dodt 
-\family typewriter
-<cdodt-AT-fcoe.k12.ca.us>
-\family default
- Bug reports and Windows ideas.
- Patches for Windows installer.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Olivier\InsetSpace ~
-Aubert 
-\family typewriter
-<oaubert-AT-bat710.univ-lyon1.fr>
-\family default
- New magics.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-King\InsetSpace ~
-C.\InsetSpace ~
-Shu 
-\family typewriter
-<kingshu-AT-myrealbox.com>
-\family default
- Autoindent patch.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Chris\InsetSpace ~
-Drexler 
-\family typewriter
-<chris-AT-ac-drexler.de>
-\family default
- Readline packages for Win32/CygWin.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gustavo\InsetSpace ~
-Cordova\InsetSpace ~
-Avila 
-\family typewriter
-<gcordova-AT-sismex.com>
-\family default
- EvalDict code for nice, lightweight string interpolation.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Kasper\InsetSpace ~
-Souren 
-\family typewriter
-<Kasper.Souren-AT-ircam.fr>
-\family default
- Bug reports, ideas.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gever\InsetSpace ~
-Tulley 
-\family typewriter
-<gever-AT-helium.com>
-\family default
- Code contributions.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Ralf\InsetSpace ~
-Schmitt 
-\family typewriter
-<ralf-AT-brainbot.com>
-\family default
- Bug reports & fixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Oliver\InsetSpace ~
-Sander 
-\family typewriter
-<osander-AT-gmx.de>
-\family default
- Bug reports.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Rod\InsetSpace ~
-Holland 
-\family typewriter
-<rhh-AT-structurelabs.com>
-\family default
- Bug reports and fixes to logging module.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Daniel\InsetSpace ~
-'Dang'\InsetSpace ~
-Griffith 
-\family typewriter
-<pythondev-dang-AT-lazytwinacres.net>
-\family default
- Fixes, enhancement suggestions for system shell use.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Viktor\InsetSpace ~
-Ransmayr 
-\family typewriter
-<viktor.ransmayr-AT-t-online.de>
-\family default
- Tests and reports on Windows installation issues.
- Contributed a true Windows binary installer.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Mike\InsetSpace ~
-Salib 
-\family typewriter
-<msalib-AT-mit.edu>
-\family default
- Help fixing a subtle bug related to traceback printing.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-W.J.\InsetSpace ~
-van\InsetSpace ~
-der\InsetSpace ~
-Laan 
-\family typewriter
-<gnufnork-AT-hetdigitalegat.nl>
-\family default
- Bash-like prompt specials.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Antoon\InsetSpace ~
-Pardon 
-\family typewriter
-<Antoon.Pardon-AT-rece.vub.ac.be>
-\family default
- Critical fix for the multithreaded IPython.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-John\InsetSpace ~
-Hunter 
-\family typewriter
-<jdhunter-AT-nitace.bsd.uchicago.edu>
-\family default
- Matplotlib author, helped with all the development of support for matplotlib
- in IPyhton, including making necessary changes to matplotlib itself.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Matthew\InsetSpace ~
-Arnison 
-\family typewriter
-<maffew-AT-cat.org.au>
-\family default
- Bug reports, `
-\family typewriter
-%run -d
-\family default
-' idea.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Prabhu\InsetSpace ~
-Ramachandran 
-\family typewriter
-<prabhu_r-AT-users.sourceforge.net>
-\family default
- Help with (X)Emacs support, threading patches, ideas...
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Norbert\InsetSpace ~
-Tretkowski 
-\family typewriter
-<tretkowski-AT-inittab.de>
-\family default
- help with Debian packaging and distribution.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-George\InsetSpace ~
-Sakkis <
-\family typewriter
-gsakkis-AT-eden.rutgers.edu>
-\family default
- New matcher for tab-completing named arguments of user-defined functions.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-J�rgen\InsetSpace ~
-Stenarson 
-\family typewriter
-<jorgen.stenarson-AT-bostream.nu>
-\family default
- Wildcard support implementation for searching namespaces.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Vivian\InsetSpace ~
-De\InsetSpace ~
-Smedt 
-\family typewriter
-<vivian-AT-vdesmedt.com>
-\family default
- Debugger enhancements, so that when pdb is activated from within IPython,
- coloring, tab completion and other features continue to work seamlessly.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Scott\InsetSpace ~
-Tsai 
-\family typewriter
-<scottt958-AT-yahoo.com.tw>
-\family default
- Support for automatic editor invocation on syntax errors (see 
-\begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython/issue36}
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Alexander\InsetSpace ~
-Belchenko 
-\family typewriter
-<bialix-AT-ukr.net>
-\family default
- Improvements for win32 paging system.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Will\InsetSpace ~
-Maier 
-\family typewriter
-<willmaier-AT-ml1.net>
-\family default
- Official OpenBSD port.
-\end_layout
-
-\end_body
-\end_document

doc/update_magic.sh

@@ -1,2 +0,0 b''
-#!/bin/sh
-ipython --magic_docstrings > magic.tex
  No newline at end of file

doc/update_manual.py

@@ -1,28 +0,0 b''
-#!/usr/bin/env ipython
-""" Must be launched via ipython not normal python 
-
-Run by:
-    
-    ipython update_manual.py
-"""
-
-import sys,IPython,re
-
-fil=open("magic.tex","w")
-oldout=sys.stdout
-sys.stdout=fil
-_ip.magic("magic -latex")
-sys.stdout=oldout
-fil.close()
-
-fil=open("manual_base.lyx")
-txt=fil.read()
-fil.close()
-
-manualtext=re.sub("__version__",IPython.__version__,txt)
-fil=open("manual.lyx","w")
-fil.write(manualtext)
-fil.close()
-print "Manual (magic.tex, manual.lyx) succesfully updated, exiting..."
-import os
-os.abort()

tools/bkp.py

@@ -1,72 +0,0 b''
-#!/usr/bin/env python
-"""Backup directories using rsync. Quick and dirty.
-
-backup.py config_file final_actions
-"""
-
-#----------------------------------------------------------------------------
-# configure in this section
-
-# all dirs relative to current dir.
-
-# output directory for backups
-outdir = ''
-
-# list directories to backup as a dict with 1 or 0 values for
-# recursive (or not) descent:
-to_backup = {}
-
-# list exclude patterns here (space-separated):
-# if the pattern ends with a / then it will only match a directory, not a
-# file, link or device.
-# see man rsync for more details on the exclude patterns
-exc_pats = '#*#  *~  *.pyc *.pyo *.o '
-
-# global options for rsync
-rsync_opts='-v -t -a --delete --delete-excluded'
-
-#----------------------------------------------------------------------------
-# real code begins
-import os,string,re,sys
-from IPython.genutils import *
-from IPython.Itpl import itpl
-
-# config file can redefine final actions
-def final():
-    pass
-
-# load config from cmd line config file or default bkprc.py
-try:
-    execfile(sys.argv[1])
-except:
-    try:
-        execfile('bkprc.py')
-    except IOError:
-        print 'You need to provide a config file: bkp.py rcfile'
-        sys.exit()
-
-# make output dir if needed
-outdir = os.path.expanduser(outdir)
-try:
-    os.makedirs(outdir)
-except OSError:  # raised if dir already exists -> no need to make it
-    pass
-
-# build rsync command and call:
-exclude = re.sub(r'([^\s].*?)(\s|$)',r'--exclude "\1"\2',exc_pats)
-rsync = itpl('rsync $rsync_opts $exclude')
-
-# the same can also be done with lists (keep it for reference):
-#exclude = string.join(['--exclude "'+p+'"' for p in qw(exc_pats)])
-
-# rsync takes -r as a flag, not 0/1 so translate:
-rec_flag = {0:'',1:'-r'}
-
-# loop over user specified directories calling rsync
-for bakdir,rec in to_backup.items():
-    bakdir = os.path.expanduser(bakdir)
-    xsys(itpl('$rsync $rec_flag[rec] $bakdir $outdir'),
-         debug=0,verbose=1,header='\n### ')
-
-# final actions?
-final()

tools/bkp.sh

@@ -1,22 +0,0 b''
-#!/bin/sh
-
-# Simple backup script for ipython, to keep around a static copy of the whole
-# project at the current version point.  We do this by exporting from SVN.
-
-# Config here
-IPYTHONSVN=$HOME/ipython/svn/ipython/trunk
-BACKUPDIR=$HOME/ipython/backup
-
-####
-# Code begins
-IPVERSION=`ipython -Version`
-IPX=ipython-$IPVERSION
-ARCHIVE=$BACKUPDIR/$IPX.tgz
-
-svn export $IPYTHONSVN $IPX
-
-tar czf $ARCHIVE $IPX
-
-rm -rf $IPX
-
-echo "Backup left in: $ARCHIVE"

tools/bkprc.py

@@ -1,22 +0,0 b''
-# config file for a quick'n dirty backup script that uses rsync
-
-# output directory for backups
-outdir = '~/tmp'
-
-# list directories to backup as a dict with 1 or 0 values for
-# recursive (or not) descent:
-to_backup = {'~/ipython/ipython':1}
-
-# exclude patterns. anything ending in / is considered a directory
-exc_pats = '#*#  *~ *.o *.pyc *.pyo MANIFEST *.pdf *.flc build/ dist/ ' \
-' doc/manual/ doc/manual.lyx ChangeLog.* magic.tex *.1.gz '
-
-# final actions after doing the backup
-def final():
-    dbg = 0
-    version = bq('ipython -V')
-    out_tgz = outdir+'/ipython-'+version+'.tgz'
-    xsys(itpl('cd $outdir; pwd;tar -czf $out_tgz ipython'),debug=dbg,verbose=1)
-    #xsys(itpl('cp $out_tgz /mnt/card/fperez/ipython'),debug=dbg,verbose=1)
-    xsys(itpl('mv $out_tgz ~/ipython/backup'),debug=dbg,verbose=1)
-    xsys(itpl('rm -rf ${outdir}/ipython'),debug=dbg,verbose=1)

tools/ipsvnc

@@ -1,78 +0,0 b''
-#!/usr/bin/env python
-"""Simple svn commit wrapper which emails a given list of people.
-
-Usage:
-
-  ipsvnc [args]
-
-This is equivalent to doing
-
-  svn commit [args]
-
-If the commit operation is successful (the script asks for confirmation), a
-hardwired list of maintainers is informed of the commit.
-
-This is a poor-man's substitute for a proper svn post-commit hook with an
-ipython-svn email list, which we're waiting to get soon.  It should be removed
-once that facility is in place.
-
-This only works on a unix box which can send mail by itself."""
-
-import os
-import commands
-import sys
-import time
-
-# Package maintainers to be alerted
-maintainers = ['[e-mail]', '[e-mail]', '[e-mail]',
-               '[e-mail]']
-
-#maintainers = ['[e-mail]']  # dbg
-
-# Assemble command line back, before passing it to svn
-svnargs = []
-for arg in sys.argv[1:]:
-    if ' ' in arg:
-        svnargs.append('"%s"' % arg)
-    else:
-        svnargs.append(arg)
-svnargs = ' '.join(svnargs)
-
-#print 'SVN args: <%s>' % svnargs; sys.exit()  # dbg
-
-# perform commit
-print 'Performing SVN commit, this may take some time...'
-os.system('svn commit %s' % svnargs)
-svntime = time.asctime()
-print 'Getting SVN log and version info...'
-svnstatus = commands.getoutput('svn log -r HEAD')
-svnversion = commands.getoutput('svnversion .').split(':')[-1]
-
-# Confirm with user (trying to get the status from the svn commit blocks
-# silently, I don't care to debug it)
-ans = raw_input('If commit was succesful, proceed '
-                'with email notification? [Y/n] ')
-if ans.lower().startswith('n'):
-    print "Exiting now..."
-    sys.exit(1)
-else:
-    print "OK.  Emailing maintainers..."
-
-# Send emails
-subject = "[IPython SVN] New commit performed by %s" % os.getlogin()
-body = """\
-Commit performed at: %s
-
-SVN arguments used: %s
-
-SVN Version: %s
-
-This version probably points to this changeset:
-http://projects.scipy.org/ipython/ipython/changeset/%s
-
-Current SVN status after last commit:
-%s""" % (svntime,svnargs,svnversion,svnversion,svnstatus)
-
-for maint in maintainers:
-    print "Emailing",maint
-    os.system('echo "%s" | mail -s "%s" %s' % (body, subject,maint))

tools/lyxport

@@ -1,1049 +0,0 b''
-#!/usr/bin/env perl
-#
-#*****************************************************************************
-#
-#   lyxport - script for exporting lyx docs to HTML, PostScript and PDF
-#
-#   Inspired on the lyx2html script by Steffen Evers ([e-mail])
-#   (many thanks to him).
-#
-#      Copyright (C) 2001  Fernando Pérez ([e-mail])
-#
-#*****************************************************************************
-#
-#      This program is free software; you can redistribute it and/or modify
-#      it under the terms of the GNU General Public License as published by
-#      the Free Software Foundation; either version 2 of the License, or
-#      (at your option) any later version.
-#
-#      This program is distributed in the hope that it will be useful,
-#      but WITHOUT ANY WARRANTY; without even the implied warranty of
-#      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#      GNU General Public License for more details.
-#
-#      If you do not have a copy of the GNU General Public License, write
-#      to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
-#      MA 02139, USA.
-#
-#      If the author of this software was too lazy to include the full GPL
-#      text along with the code, you can find it at:
-#
-#                 http://www.gnu.org/copyleft/gpl.html
-#
-#*****************************************************************************
-
-=pod
-
-=head1 NAME
-
-B<lyxport> - Export a LyX or LaTeX file to HTML, PostScript and PDF.
-
-=head1 SYNOPSIS
-
-B<lyxport> [options] F<file>
-
-Perl script which takes a LyX or LaTeX file as its only argument and produces
-HTML, PostScript and PDF versions of the document. The name is short for "lyx
-export".
-
-You can call B<lyxport> with a filename with or without extension: F<file>,
-F<file.lyx> and F<file.tex> will all work. B<lyxport> will update the LaTeX
-file if there is a corresponding LyX file with a newer timestamp.
-
-Use B<lyxport --help> for more information, and B<lyxport --man> for a full
-man page.
-
-=cut
-
-#*****************************************************************************
-# modify here the command names to suit your local conditions
-my %cmd= (
-	  lyx => "/usr/bin/lyx",
-	  latex => "latex",
-	  latex2html => "latex2html",
-	  dvips => "dvips",
-	  pdflatex => "pdflatex",
-	  epstopdf => "epstopdf"
-	 );
-
-#************ DO NOT CHANGE ANYTHING BELOW THIS ULESS YOU *REALLY* KNOW
-#************ WHAT YOU ARE DOING.
-
-#*****************************************************************************
-# modules and globals
-use strict;
-use File::Copy;
-use File::Basename;
-my (%opt);                   # command line options
-my $version = "0.3.2";        # keep this up to date with the docs (at end)!
-
-#*****************************************************************************
-# "main" (simple minded way to keep variable scoping under control)
-main();
-
-sub main {
-    my ($runs,			# number of latex runs
-	$file_in,		# input filename as given at cmd line
-	$file_base,		# base (no extension) name of file to work on
-	$lyx_time,		# timestamps of lyx/tex files
-	$tex_time,
-	$l2h_file,               # tex file cleaned up for latex2html
-	$targets_built,
-	$targets_failed,
-	$status,                 # status string for diagnostics printing
-	@latex_from_lyx         # LaTeX files was created from LyX file
-       );
-
-    #------------------------------------------------------------------------
-    # code begins
-
-    cmdline_process(\%opt,\$file_in);
-
-    # set defaults and filenames needed throughout
-    $runs=$opt{runs};
-    set_cmd_defaults(\%cmd);
-    $file_base=check_file_exists($file_in);
-    # various filenames (with extensions)
-    my @exts=qw(lyx tex aux dvi log ps pdf out toc);
-    my ($lyx,$tex,$aux,$dvi,$log,$ps,$pdf,$out,$toc) = map { "$file_base.$_" } @exts;
-
-    # first, if tex file is older than lyx file, update
-    @latex_from_lyx=update_tex($lyx,$tex);
-
-    if ($opt{clean}) {
-	lyxport_info("Cleanup of old auxiliary files requested");
-	safe_system("rm -rf $file_base");
-	unlink ($aux,$log,$out,$toc);
-    }
-
-    # run latex for both html (needs .aux file) and ps (needs .dvi)
-    if ($opt{html} or $opt{ps}) {
-	run_latex("$cmd{latex} -interaction=nonstopmode",$tex,\$runs);
-    }
-    # now make targets
-    if ($opt{html}) {
-	make_html($tex,$file_base,$opt{opts_l2h},\$status,
-		  \$targets_built,\$targets_failed);
-    }
-    if ($opt{ps}) {
-	make_ps($dvi,$ps,$file_base,\$status,\$targets_built,\$targets_failed);
-    }
-    if ($opt{pdf}) {
-	make_pdf($tex,$pdf,\$runs,$file_base,
-		 \$status,\$targets_built,\$targets_failed);
-    }
-
-    #cleanup before exiting and print some diagnostics info
-    unless ($opt{debug}) {
-	unlink ($dvi,$log,$out);
-    }
-    # extra cleanup
-    if ($opt{tidy}) {
-	print "tidy up $opt{tidy},$aux,$log,$out,$toc,@latex_from_lyx\n";
-	tidy_up($opt{tidy},$aux,$log,$out,$toc,@latex_from_lyx);
-    }
-    final_diagnostics($file_in,$status,$targets_built,$targets_failed);
-    exit(0);
-} # end of main()
-
-#*****************************************************************************
-# subroutines
-
-#-----------------------------------------------------------------------------
-sub make_html {
-    my($tex,$html_dir,$opts_l2h,$stat_ref,$built_ref,$failed_ref)=@_;
-    my($success);
-
-    lyxport_info("Making HTML");
-    run_latex2html($tex,$opts_l2h);
-    $success=check_targets("${html_dir}/${html_dir}.html",'HTML',
-			   $built_ref,$failed_ref);
-    if ($success) {$$stat_ref .= "Target HTML built in directory $html_dir\n" }
-} # end of make_html()
-
-#-----------------------------------------------------------------------------
-sub make_ps {
-    my($dvi,$ps,$html_dir,$stat_ref,$built_ref,$failed_ref)=@_;
-    my($success);
-
-    lyxport_info("Making PostScript");
-    safe_system("$cmd{dvips} $dvi -o $ps");
-    $success=check_targets($ps,'PostScript',$built_ref,$failed_ref);
-    if ($success and not $opt{leave}) {
-	move2html_dir('PostScript',$ps,$html_dir,$stat_ref,$built_ref);
-    }
-} # end of make_ps()
-
-#-----------------------------------------------------------------------------
-sub make_pdf {
-    my($tex,$pdf,$runs_ref,$html_dir,$stat_ref,$built_ref,$failed_ref)=@_;
-    my($success);
-
-    lyxport_info("Making PDF");
-    run_pdflatex($tex,$pdf,$runs_ref);
-    $success=check_targets($pdf,'PDF',$built_ref,$failed_ref);
-    if ($success and not $opt{leave}) {
-	move2html_dir('PDF',$pdf,$html_dir,$stat_ref,$built_ref);
-    }
-} # end of make_pdf()
-
-#-----------------------------------------------------------------------------
-# move a given target to the html dir, only if it exists. leaves diagnostics 
-# info in a status string
-sub move2html_dir {
-    my($name,$file,$dir,$stat_ref,$html_status_ref)=@_;
-
-    if ($$html_status_ref =~ /HTML/) {
-	safe_system("mv $file $dir");
-	$$stat_ref .= "Target $name moved to directory $dir\n";
-    } else {
-	$$stat_ref .= "Target $name left in current directory\n";
-    }
-} # end of move2html_dir()
-
-#-----------------------------------------------------------------------------
-# make sure that the tex file is up to date vs the lyx original before starting
-# returns a list of the included .tex files which were generated (besides the main one)
-sub update_tex {
-    my($lyx,$tex)=@_;
-    my($lyx_time,$tex_time);
-    my(@lyx_out,@made_tex,$lc);
-
-    @made_tex=();
-    unless (-e $lyx) {
-	print "LyX file not found. Working off the LaTeX file alone.\n\n";
-	return;
-    }
-    $lyx_time=(stat($lyx))[9];
-    $tex_time=(stat($tex))[9];
-    if ($lyx_time>$tex_time or not(-e $tex)) { 
-	lyxport_info("LaTeX file outdated or not existent, regenerating it...");
-	unlink $tex;
-	@lyx_out=`$cmd{lyx} -dbg latex --export latex $lyx 2>&1 `;
-	# try again without -dbg option: LyX has a bug here! Note that this will
-	# disable the ability to remove extra .tex files generated from \include
-	# statements. But at least it will work, until they fix the bug in LyX.
-	unless (-e $tex) {
-	    @lyx_out=`$cmd{lyx} --export latex $lyx 2>&1 `;
-	}
-	# end of ugly workaround
-	unless (-e $tex) {die "Aborting: couldn't create LaTeX file with LyX.\n\n"};
-	push (@made_tex,$tex);
-	# find whether lyx made auxiliary (included) .tex files and report
-	foreach $lc (0..$#lyx_out-1) {
-	    $_=$lyx_out[$lc];
-	    if (/^incfile:.*\.lyx/) { 
-		$lyx_out[$lc+1] =~ /^writefile:(.*)$/;
-		push (@made_tex,basename($1));
-	    }
-	}
-	if (@made_tex) {
-	    lyxport_info("Made LaTeX included files: @made_tex");
-	}
-	lyxport_info("Done with LaTeX generation. Moving on.");
-    }
-    return @made_tex;
-} # end of update_tex()
-
-#-----------------------------------------------------------------------------
-# run latex on a file as many times as needed
-# if the given # of runs is > 0, that many are done; otherwise latex is run
-# as many times as needed until cross-references work.
-# can be used to run either normal latex or pdflatex
-sub run_latex {
-    my($latex_cmd,$file,$runs_ref)=@_;
-
-    # pre-determined # of runs
-    if ($$runs_ref > 0) {
-	foreach (1..$$runs_ref) {
-	    lyxport_info("$latex_cmd run # $$runs_ref");
-	    safe_system("$latex_cmd $file");
-	}
-    }
-    # or make as many runs as needed to get things right (not very robust...)
-    else {
-	$$runs_ref=0;
-	while (1) {
-	    $$runs_ref++;
-	    lyxport_info("$latex_cmd run # $$runs_ref");
-	    $_ = `$latex_cmd $file`;
-	    print;
-	    last unless (/Rerun to get cross-references right/m or 
-			 /^No file .*\.toc.$/m);
-	}
-    }
-} # end of run_latex()
-
-#-----------------------------------------------------------------------------
-# cleanup the tex code so that latex2html doesn't get too confused
-# this is essentially a Perl version (made with s2p) of Steffan Effer's
-# original improvetex sed script, part of his lyx2html script collection
-sub improve_tex4html {
-    my ($texfile,$newfile)=@_;
-    my ($len1,$pflag);
-    my $printit=1;
-    local *OLD,*NEW;
-
-    open(OLD,"< $texfile") || die "Can't read from file $texfile: $!\n";
-    open(NEW,"> $newfile") || die "Can't write to file $newfile: $!\n";
-    select(NEW) || die "Can't make $newfile default filehandle: $!\n";
-
-# code generated by s2p follows. Emacs can't reindent it properly!
-# this code is ugly (once in Perl, original sed was ok). Clean it up...
-$pflag=$\; # save print flag
-$\="\n";
-LINE:
-while (<OLD>) {
-    chomp;
-    # remove pagerefs over two lines (senseless in HTML)
-    if (/on *$\|on *page *$/) {
-	$_ .= "\n";
-	$len1 = length;
-	$_ .= <OLD>;
-	chop if $len1 < length;
-	s/on *\n*page *\n*\\pageref{[^}]*}/\n/g;
-    }
-    # remove regular pagerefs (senseless in HTML)
-    s/on *page *\\pageref{[^}]*}//g;
-    # comment out redefintion of url tag (confuses latex2html)
-    if (/^\\IfFileExists{url.sty}/) {
-	s/^/%/;
-	print;
-	$_ = <OLD>;
-	s/^/%/;
-    }
-    # remove empty pages
-    if (/^\\thispagestyle{empty}~\\newpage$/) {
-        $printit = 0;
-        next LINE;
-    }
-    if (/^\\thispagestyle{empty}~$/) {
-        $printit = 0;
-        next LINE;
-    }
-    # remove custom latex commands for fancyheaders
-    s/\\fancyhead[^{]*{[^{}]*([^{}]*{[^{}]*})*[^{}]*}*//g;
-    s/\\thispagestyle{[^{}]*}//g;
-    # change documentclass from scrbook to book
-    s/^(\\documentclass[^{}]*{)scrbook}/$1book}/;
-    # comment out unsupported packages
-    s/^(\\usepackage\[T1\]{fontenc})/%$1/;
-    s/^(\\usepackage{a4wide})/%$1/;
-    s/^(\\usepackage{fancyhdr})/%$1/;
-    s/^(\\usepackage{ae)/%$1/;
-    s/^(\\pagestyle{fancy})/%$1/;
-    # the geometry package doesn't make sense in html
-    s/^(\\usepackage{geometry})/%$1/;
-    s/^(\\geometry)/%$1/;
-    # comment out ident/skip block command (produces error message; why?)
-    s/^(\\setlength\\parskip{.*})/%$1/;
-    s/^(\\setlength\\parindent{.*})/%$1/;
-} continue {
-    if ($printit) { print }
-    else { $printit++ }
-}
-close(OLD);
-close(NEW);
-select(STDOUT);
-$\=$pflag; # restore defaults
-}  # end of improve_tex4html()
-
-#-----------------------------------------------------------------------------
-sub run_latex2html {
-    my ($tex,$latex2html_opts)=@_;
-    my ($l2h_file,$symlink_exists,$htmldir);
-
-    ($htmldir=$tex) =~ s/\.tex$//;
-    $l2h_file="${tex}_#tmp_2html#";
-    improve_tex4html($tex,$l2h_file);
-    # add index support
-    my $xtraargs = "";
-    my $idx = "$htmldir.idx";
-    if(-e $idx ) {
-            $xtraargs .= "-index $idx";
-    }
-    safe_system("$cmd{latex2html} $xtraargs $latex2html_opts $l2h_file");
-    unless ($opt{debug}) {
-	unlink($l2h_file,"$htmldir/labels.pl");
-    }
-
-    # latex2html always leaves 2 copies of the file (one as file.html, one as 
-    # index.html). In systems that support symlinks, remove one and replace it 
-    # with a link:
-    $symlink_exists = eval { symlink("",""); 1 };
-    if ($symlink_exists) {
-	unlink("$htmldir/index.html");
-	symlink("$htmldir.html","$htmldir/index.html");
-    }
-} # end of run_latex2html()
-
-#-----------------------------------------------------------------------------
-# remove calls to eps figures if they have an accompanying tiff, jpg or png
-sub improve_tex_figs {
-    my ($tex,$textmp)=@_;
-    local (*TEX,*TMP);
-
-    # begin changes to tex file
-    my ($printit,$figname,$fignoneps,$figbase,$figext,$fignew,@figlist,@tmpfiles);
-    open(TEX,"< $tex") || die "Can't read from LaTeX file $tex: $!\n";
-    open(TMP,"> $textmp") || die "Can't write to temp file $textmp: $!\n";
-    $printit=1;
-    while (<TEX>) {
-	if (/includegraphics{([^\}]*)/) {
-	    $figname=$1;
-	    # remove .eps from fig name and make a .pdf version if necessary
-	    if ($figname =~ /\.eps$/i) {
-		($figbase = $figname) =~ s/\.eps$//i;
-		# now we need to find if there's any non-eps figure for this file:
-		# pdflatex can handle jpegs, tiffs, etc. So we only need to build
-		# an associated pdf if there is no other figure file for pdflatex
-		# to work with
-		@figlist=grep {/\.jpe?g$|\.tiff?$|\.png$|\.pdf$/i} <$figbase.*>;
-		if (@figlist > 1) {
-		    lyxport_info("Problem! More than one figure file found: @figlist");
-		    die "I don't know what to do here. Sorry, aborting...\n\n";
-		} elsif (@figlist==1) {
-		    # problem: pdftex only recognizes jpg (not jpeg, not JPG, etc)
-		    # and tif (not tiff, not TIF, etc). It also gets confused by files
-		    # called a.b.c.jpg (it thinks .b.c.jpg is the extension). argh!!!
-		    ($fignoneps)=(@figlist);
-		    # so first, extract the 3 or 4 letter extension and lowercase it
-		    $fignoneps =~ /.*\.(....??)$/;
-		    ($figext = $1) =~ tr/[A-Z]/[a-z]/;
-		    # and remove any periods from the base of the name (replace by _)
-		    $figbase =~ s/\./_/g;
-		    $fignew="$figbase.$figext";
-		    if ($fignoneps =~ /\.JPE?G$|\.TIFF?$|\.PNG$|\.PDF$/) {
-			lyxport_info("pdflatex only recognizes the following extensions:\n".
-				     "pdf, png, jpg, tif. (all lowercase, no variations like jpeg or tiff).\n".
-				     "lyxport will make a copy of $fignoneps to $fignew so that pdflatex is happy");
-			copy($fignoneps,$fignew);
-			push(@tmpfiles,$fignew);
-		    }
-		    s/$figname/$fignew/;  # in $_, for printing to temp file
-		} else {
-		    s/$figname/$figbase.pdf/;
-		    lyxport_info("Making PDF figure <$figbase.pdf> from <$figname>");
-		    safe_system("$cmd{epstopdf} $figname");
-		}
-
-	    }
-	}
-    } continue {
-	if ($printit) { print TMP $_}
-	else { $printit++ }
-    }
-    close(TEX);
-    close(TMP);
-    return @tmpfiles;
-}  # end of improve_tex_figs()
-
-#-----------------------------------------------------------------------------
-# Make the pdf directly from the latex file
-# Notes: for this to work ok, the following must have been done:
-# 1. ~/.dvipsrc file must contain the lines
-#    p+ psfonts.cmz
-#    p+ psfonts.amz
-# 2. The latex preamble of the lyx file must have
-#    \usepackage{ae,aecompl}
-# This is so that T1 encoded fonts come out looking good in the final pdf.
-sub run_pdflatex {
-    my ($tex,$pdf,$runs_ref)=@_;
-    my ($texbase,$tmpbase,$textmp,@tmpfiles,@extensions,$printit);
-    local *TEX,*TMP;
-
-    # first fix references to eps figures (make sure that pdf versions exist!!!)
-    # make all changes in a temp tex file
-    ($texbase=$tex) =~ s/\.tex$//;
-    $tmpbase = "${texbase}_#tmp_pdf#";
-    @extensions=qw(tex aux out toc log);
-    ($textmp,@tmpfiles)= map { "${tmpbase}.$_" } @extensions;
-
-    push(@tmpfiles,improve_tex_figs($tex,$textmp));
-    # now run the actual pdflatex converter
-    run_latex("$cmd{pdflatex} -interaction=nonstopmode",$textmp,$runs_ref);
-    rename( "${tmpbase}.pdf",$pdf);
-    unless ($opt{debug}) { unlink ($textmp,@tmpfiles,"texput.log"); }
-} # end of run_pdflatex()
-
-#-----------------------------------------------------------------------------
-# general utility routines (not related to latex/html/pdf) follow
-
-#-------------------------------------------------------------------------
-sub cmdline_process{
-    my($opt_ref,$file_ref)=@_;
-
-    # modules
-    no strict "vars";  # avoid some unpleasant warnings while checking options
-
-    use Getopt::Long;
-    # allow bundling of single letter options (-a -b == -ab)
-    Getopt::Long::Configure ("bundling");
-    use Pod::Usage;
-
-    # note: the second name for each option (after |) is an alias for user
-    # convenience only. Internally, the only created hash entries use the *first*
-    # name as a key (i.e. $opt{h} doesn't exist, $opt{html} is set with -h or --html)
-    my(@option_list) = qw(html|h ps|p pdf|f leave
-			  runs|r=i opts_l2h|o=s clean|c tidy|t+
-			  cld|l debug|d help man|m version|v);
-
-    # debug mode overrides all post-run cleanup options
-    if ($opt{debug}) { $opt{t}=0 }
-
-    # default: a negative # of runs means auto-detect
-    $$opt_ref{runs}= -99;
-    # dash options first
-    GetOptions($opt_ref,@option_list)  ||  pod2usage(-verbose => 0);
-
-    # execute all possible "die" modes first
-    cmdline_debug(%$opt_ref) if ($$opt_ref{cld});
-    pod2usage(-verbose => 1)  if ($$opt_ref{help});
-    pod2usage(-verbose => 2)  if ($$opt_ref{man});
-    die "\nlyxport: version $version\n\n" if ($$opt_ref{version});
-
-    ## Now get filename (only ONE)
-    pod2usage(-verbose => 0, -message =>
-	      "\nERROR: lyxport works with exactly ONE file at a time.\n")
-      if (@ARGV != 1);
-    ($$file_ref)=@ARGV;
-
-    # choose whether to make all targets or just the explicitly specified ones
-    unless ($$opt_ref{html} or $$opt_ref{ps} or $$opt_ref{pdf}) {
-	$$opt_ref{html}=$$opt_ref{ps}=$$opt_ref{pdf}=1;
-    }
-} # end of cmdline_process()
-
-#-----------------------------------------------------------------------------
-# quick and dirty hash printing by key/value pairs
-sub print_hash {
-    my($key_msg,$val_msg,%hash)=@_;
-    my($op,$val);
-
-    while ( ($op,$val)=each(%hash) ) {print "$key_msg $op $val_msg $val\n" }
-} # end of print_hash()
-
-#-----------------------------------------------------------------------------
-sub cmdline_debug{
-    my(%opt)=@_;
-
-    print "\nlyxport command line debug mode\n";
-    print "-------------------------------\n\n";
-    print "This is a dump of your command line options, as key-value pairs:\n\n";
-    print_hash("","->",%opt);
-    print "\nExiting...\n\n";
-    exit;
-} # end of cmdline_debug()
-
-#-----------------------------------------------------------------------------
-# execute a system call but die with some info if return value is non-zero
-sub safe_system {
-    my $error;
-
-    $error=system(@_)/256;
-    if ($error) {
-	print "\nERROR: Command\n   @_\nfailed.\n";
-    }
-    return $error;
-} # end of safe_system()
-
-#-----------------------------------------------------------------------------
-# check that the command names specified at the top exist in the system, 
-# otherwise choose bare defaults and hope for the best.
-sub set_cmd_defaults {
-    my ($cmd)=@_;
-    my ($prog,$cmd_name);
-
-    print "\n";
-    while (($prog,$cmd_name)=each(%cmd)) {
-	print "Checking for program <$prog>, as <$cmd_name>... \n";
-	if (system("which $cmd_name")/256) {
-	    $$cmd{$prog}=$prog;
-	    print "Not found. Reverting to default name $prog.\n";
-	} else { print "OK, found it.\n" }
-    }
-    print "\nDone configuring command names\n\n";
-} # end of set_cmd_defaults()
-
-#-----------------------------------------------------------------------------
-# make sure there's either a .lyx or a .tex file to work with
-# returns a stripped name (without .lyx or .tex extension) of the file
-sub check_file_exists {
-    my($file_in)=@_;
-    my($base_file);
-
-    $_=$file_in;
-    if    (/\.lyx$/) { s/\.lyx$// }
-    elsif (/\.tex$/) { s/\.tex$// }
-    $base_file=$_;
-    unless (-e "${base_file}.lyx" or -e "${base_file}.tex") {
-	die "I can't find a LyX or LaTeX file to work with!\nAborting...\n\n";
-    }
-    return $base_file;
-} # end of check_file_exists()
-
-#-----------------------------------------------------------------------------
-sub check_targets{
-    my($file,$tag,$built,$failed)=@_;
-    my($success)=0;
-
-    $tag .= ' ';
-    if (-s $file) { $$built .= $tag; $success=1; }
-    else { $$failed .= $tag }
-    return $success;
-} # end of check_targets()
-
-#-----------------------------------------------------------------------------
-# do extra cleaning of aux, toc, log files generated during running
-sub tidy_up {
-    my($tidy,$aux,$log,$out,$toc,@latex_from_lyx)=@_;
-
-    lyxport_info("Cleanup of leftover auxiliary files");
-    print "Removing files: $aux, $log, $out, $toc\n";
-    unlink ($aux,$log,$out,$toc);
-    if ($tidy>1 and @latex_from_lyx) {
-	lyxport_info("Extra cleanup: removing LaTeX file(s) @latex_from_lyx");
-	unlink(@latex_from_lyx);
-	foreach (@latex_from_lyx) {
-	    s/\.tex$/\.aux/;
-	    if (-e) {
-		print "Removing aux file $_\n";
-		unlink($_);
-	    }
-	}
-    }
-} # end of tidy_up()
-
-#-----------------------------------------------------------------------------
-sub lyxport_info {
-    my ($target)=@_;
-
-    print "\n",'*'x75,"\n";
-    print "<lyxport> $target\n\n";
-} # end of lyxport_info()
-
-#-----------------------------------------------------------------------------
-sub final_diagnostics{
-    my($file_in,$status,$targets_built,$targets_failed)=@_;
-
-    lyxport_info("All done!");
-    print "Input file: $file_in\n\n";
-    print "Targets built : $targets_built\n\n";
-    if ($targets_failed) {
-	print "PROBLEM!\nTargets failed: $targets_failed\n\n";
-    }
-    print "Diagnostics of build process:\n\n$status\nBye!\n\n";
-} # end of final_diagnostics()
-
-
-#************************ end of code for <lyxport> *******************
-
-__END__
-
-=pod
-
-=head1 DESCRIPTION
-
-=head2 Purpose
-
-LyX ( http://www.lyx.org ) is a wonderful document processor, which can produce
-from a single source multiple versions for different purposes: a PostScript
-file for printing on a Unix-type system, a PDF file for distribution across
-multiple operating systems, or an HTML file for Internet display. It
-accomplishes this by exporting its own file format to a LaTeX file and then
-running various converters on this resulting file.
-
-However, it turns out that this process isn't exactly foolproof, as these
-converters have all sorts of little quirks which can produce anything from
-surprises in the way the final result looks like to outright failure of the
-export process. The purpose of B<lyxport> is to serve as a "smart wrapper"
-around those export facilities which LyX normally uses, trying to massage the
-LaTeX file that everything starts from in the hopes of having better success
-in producing HTML and PDF (PostScript usually poses no problems). 
-
-B<lyxport> also allows you to keep around only the LyX file, and possibly any
-ancillary figure files. B<lyxport> takes care of generating (and removing
-afterwards if instructed to do so) any intermediate files necessary for the
-export process.
-
-For example, in order to make PDF from a LaTeX file, any included eps figures
-need to be converted to pdf format. But LyX likes to have the figures in eps
-format for on-screen display, which is a great feature to have. B<lyxport>
-allows you to keep your LyX file as usual (with references to .eps figures)
-and will make .pdf versions of any included figure on the fly as needed. You
-can even ask it to remove those pdf files after it finishes, if you really
-want to maintain a minimum of files around (though it will have to remake them
-again if you ever need to update your pdf exported document).
-
-=head2 Command line use
-
-If you simply type B<lyxport> F<file>, it will try to make PostScript, HTML,
-and PDF versions of your file, putting them all in a single directory named
-F<file> (without a .lyx or .tex extension if your file had one). But it has
-L<command line options|OPTIONS AND ARGUMENTS> for making only the
-formats you want, and fairly detailed control over its behavior.
-
-=head2 If you don't have LyX
-
-Despite its name, if you are a regular LaTeX user and don't even have LyX
-installed in your system, B<lyxport> can still be useful to you. In fact,
-B<lyxport> only uses LyX once in each run: if there is no F<file.tex> or if
-F<file.lyx> file is newer than F<file.tex>, B<lyxport> updates F<file.tex>
-from F<file.lyx>. But if there is no F<file.lyx> at all it will simply use
-F<file.tex> and proceed with all its functionality intact.
-
-=cut
-###########################################################################
-=pod
-
-=head1 OPTIONS AND ARGUMENTS
-
-Single letter options (preceded by a single dash B<->) can be bundled: B<-pf>
-is equivalent to B<-p -f>. Long options (preceded by two dashes B<-->) can be
-abbreviated to as few letters as needed to clear ambiguity.
-
-=over
-
-=item B<-r --runs> I<NUM>
-
-Set number of latex runs by hand (otherwise auto-determined).
-
-=item B<-o --opts_l2h> I<'string'>
-
-String with options to be passed to B<latex2html>. This string should be
-protected by single quotes to allow double quotes inside of it.
-
-For example, if you want to pass to B<latex2html> the option B<-info "my
-info"> you can do so with B<lyxport -o ' -info "my info" '> (the extra spaces
-around the quote marks are not needed, they are here only for the sake of
-clarity).
-
-B<latex2html> has I<many> command-line options. For a project you are working
-constantly on, it may be more convenient to permanently set some of those
-options via a file called F<.latex2html-init> which B<latex2html> always
-reads at startup. See the B<latex2html> man page or the excellent online
-documentation kept at http://www-texdev.mpce.mq.edu.au/l2h/docs/manual for
-full details.
-
-=item B<-h --html>
-
-Export to HTML.
-
-=item B<-p --ps>
-
-Export to PostScript.
-
-=item B<-f --pdf>
-
-Export to PDF. See below the section L<PDF GENERATION> for details on how to
-obtain nice-looking PDF from your LaTeX sources.
-
-If none of the three above options is specified, the default behavior is to
-export I<all> three formats. If any is given, then only those formats
-explicitly specified will be produced (e.g. B<-h -f> makes HTML and PDF only,
-but not PostScript).
-
-=item B<--leave>
-
-By default lyxport moves the resulting PostScript and PDF files into the
-directory containing the HTML results (if it was created). This option tells
-it to leave them in the current directory.
-
-=item B<-c --clean>
-
-Do a clean start export, removing first any html directory, .aux, .log
-and .toc files which may have been left from previous runs.
-
-=item B<-t --tidy>
-
-B<lyxport> will tidy up I<after> itself, removing .aux, .log and .toc files left
-in the current directory. Use this only for "final" publication of documents, as
-those files are otherwise useful to shorten the time of runs.
-
-This option is incremental: you can call it twice (you can bundle it as
-B<-tt>). If called twice, B<lyxport> will remove also the LaTeX file
-associated with your LyX file, but I<only if> B<lyxport> I<itself created it
-in the same run>. This behavior is meant to be a safety net, so that
-B<lyxport> doesn't accidentally remove LaTeX files which you may have manually
-modified in some way.
-
-So if this option is called twice, you can start with a LyX file named F<file.lyx>
-and end up only with your original file plus a single directory named F<file> which 
-will contain F<file.html>, F<file.ps> and F<file.pdf> (plus some ancillary stuff for
-the html version). This mode of operation is obviously provided for the neatness
-freaks amongst us.
-
-=item B<-d --debug>
-
-Debugging mode: B<lyxport> will leave I<all> temporary files it creates lying
-around. If a particular target refuses to build, you can then try to run the
-respective commands on the temporary files manually, and possibly diagnose the
-source of the problem.
-
-This option will override any calls made to option B<--tidy>.
-
-=item B<-l --cld>
-
-Special command-line debugging mode: only prints (in a rather primitive form)
-the names and values of all command-line options which were set. Useful for
-finding problems with complicated option strings being passed to
-B<latex2html>.
-
-=item B<--help>
-
-Print this help and quit.
-
-=item B<-m --man>
-
-Print a complete man page. B<lyxport> is documented using embedded pod
-strings, so you can see its full documentation using the command B<perldoc
-lyxport>.
-
-You can also convert this documentation to other formats using the
-I<pod2_anything> family of converters (L<pod2html>, L<pod2latex>, L<pod2man>
-and L<pod2text>). See their respective man pages for details.
-
-Note that if you installed B<lyxport> properly, you should already have a man
-page available, plus html and plain text versions of the documents. These are
-by default installed to a directory named F</usr/local/doc/lyxport-XXX>, where
-F<XXX> is the version number. At installation time, you may manually change
-the F</usr/local> prefix. Consult your local documents or ask your system
-administrator for details on the specifics of your configuration.
-
-=item B<-v --version>
-
-Print version information and quit.
-
-=item B<filename>
-
-The given filename may have a .lyx or .tex extension (or none at
-all). I<lyxport> will update the tex file from the lyx file if necessary.
-
-B<lyxport> accepts only I<one> filename at a time.
-
-=back
-
-=cut
-###########################################################################
-=pod
-
-=head1 INTEGRATION WITH LyX
-
-If you find that B<lyxport> is more succesful in exporting your files than
-LyX's default calls to B<latex2html> and B<pdflatex>, you can modify LyX to
-use B<lyxport> as its conversion routine. For LyX versions 1.1.6 and above, go
-to C<< Edit->Preferences->Converters->Converters >> and specify B<lyxport> as your
-converter for C<< LaTeX->HTML >> and C<< LaTeX->PDF >>. LyX's convention
-is to call B<$$i> the current file.
-
-For example, if you want to setup B<lyxport> to be your PDF export filter
-under LyX, in the C<Converters> dialog, in the C<< LaTeX->PDF(pdflatex) >>
-option, set:
-
-    lyxport --pdf $$i
-
-This way you'll be able to export to pdf directly from within LyX, even if
-your figures are in eps format.
-
-LyX's C<Converters> dialog is a bit confusing: after making changes, you must
-first press the C<Modify> button for your changes to actually be recorded, and
-then C<Save>.
-
-You can similarly set up B<lyxport> to be your LaTeX to HTML converter.
-
-For LyX versions earlier than 1.1.6 (which didn't have the new Preferences
-dialog) these same options can be configured via your LyX defaults file. See
-the LyX documentation for details.
-
-=cut
-###########################################################################
-=pod
-
-=head1 PDF GENERATION
-
-=head2 Fonts
-
-Normally PDF documents made on Unix-type systems from LaTeX sources produce
-horrible looking fonts when viewed with Adobe's own Acrobat Reader. I don't
-know the many intricacies of the problem (you can search for the details on
-your own). I'll simply list here the trick that has helped I<me> solve the
-font problem. Try it, your mileage may vary.
-
-=over
-
-=item 1
-
-In your home directory, make (or modify it if it already exists) a file
-named F<.dvipsrc> which must contain the lines:
-
-    p+ psfonts.cmz
-    p+ psfonts.amz
-
-=item 2
-
-Make sure that the LaTeX preamble of your LyX file (or the part before
-C<\begin{document}> if you are using straight LaTeX files) contains:
-
-    \usepackage[T1]{fontenc}
-    \usepackage{ae,aecompl}
-
-This will guarantee that T1 encoded fonts come out looking good in the final PDF.
-
-=back
-
-=head2 Figures
-
-B<pdflatex> (if I understand correctly) only accepts filenames with a single
-B<.> in them, and only uses graphic files with extensions pdf, png, jpg and
-tif (all lowercase). B<lyxport> will do its best to analyze your latex file
-and try to change references to figures to accommodate B<pdflatex>, by
-creating temporary copies of your image files if necessary.
-
-Ideally, you should be able to have for example a figure called F<fig.1.JPG>
-along with a F<fig.1.eps> (for B<lyx> to preview it), and B<lyxport> would
-export a pdf document without leaving any more files after itself, even though
-it temporarily had to create F<fig_1.jpg> to make B<pdflatex> happy. As I
-said, ideally... If things don't quite work, try the B<--debug> option. If you
-find a fix for the problem, mail it to me: [e-mail]
-
-=head2 Links
-
-In order for URLs and similar elements to produce proper active links in the
-PDF document, you need to include in your LaTeX preamble the line
-
-    \usepackage{hyperref}
-
-=cut
-###########################################################################
-=pod
-
-=head1 REQUIRES
-
-B<lyxport> relies on some programs listed below, for the reasons indicated:
-
-=over
-
-=item B<lyx>
-
-To make LaTeX files from LyX files. Tested with lyx version 1.1.6fix1, should
-work with earlier versions (perhaps with minor changes to the way LyX is called).
-
-=item B<latex>
-
-To produce PostScript and for latex2html to work properly (cross-references).
-
-=item B<dvips>
-
-For making PostScript output.
-
-=item B<latex2html>
-
-For generating HTML from latex sources.
-
-=item B<pdflatex>
-
-For making PDF output from a latex file with proper cross-referencing and
-internal document links.
-
-=item B<epstopdf>
-
-A Perl script to automatically generate pdf versions of eps figures included
-in lyx files. It is more robust in its handling of various eps quirks than a
-straight call to B<ps2pdf>.
-
-=item B<perl>
-
-Well, it's a Perl script after all, isn't it?
-
-=back
-
-However, partial use of B<lyxport> is still possible without some of these
-components. If for example you don't have B<latex2html> in your system, you
-can still use B<lyxport> to produce PostScript and PDF. Various combinations
-are possible.
-
-=head2 Portability
-
-There are calls in B<lyxport> to some Unix commands like B<rm -rf>. For this
-reason it is not totally portable. These calls are however reasonably few and
-could be eliminated if there is enough demand by replacing them with
-equivalent Perl code. It's just more work...
-
-=cut
-###########################################################################
-=pod
-
-=head1 TO DO
-
-=over
-
-=item *
-
-Build rpm for more convenient installation.
-
-=item *
-
-Clean up the C<improve_tex4html()> code for readability.
-
-=back
-
-=cut
-###########################################################################
-=pod
-
-=head1 VERSION
-
-This is B<lyxport> version 0.3.1
-
-=cut
-###########################################################################
-=pod
-
-=head1 AUTHOR
-
-Fernando Pérez E<lt>[e-mail]<gt>.
-
-Please email me with comments, suggestions, bugfixes, etc.
-
-The most current version of B<lyxport> should always be available at
-http://www-hep.colorado.edu/~fperez/lyxport
-
-=cut
-###########################################################################
-=pod
-
-=head1 ACKNOWLEDGEMENTS
-
-Inspired on the B<lyx2html> script by Steffen Evers
-E<lt>[e-mail]<gt>.  Some of the code is a blatant ripoff of
-Steffen's code, using B<s2p> to get Perl versions of his original B<sed>
-scripts.
-
-=cut
-###########################################################################
-=pod
-
-
-=head1 COPYRIGHT AND DISCLAIMER
-
-This program is Copyright 2001 by Fernando Pérez.
-
-This program is free software; you can redistribute it and/or modify it under
-the terms of the GNU General Public License as published by the Free Software
-Foundation; either version 2 of the License, or (at your option) any later
-version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-If you do not have a copy of the GNU General Public License write to
-the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
-MA 02139, USA.
-
-If the author of this software was too lazy to include the full GPL text along
-with the code, you can find it at: http://www.gnu.org/copyleft/gpl.html
-
-=cut
-#************************** end of file <lyxport> **********************