Merging in ipython-ipython1b branch. This branch was used to merge in the docs from ipython1-dev,

as well as the stuff from the ipython1-sconfig branch.  In addition to simply merging the docs
from ipython1-dev, I have completely reorganized the docs to make the easier to read and write.

COPYING.txt

@@ -0,0 +1,77
+IPython is licensed under the terms of the new or revised BSD license, as follows:
+
+Copyright (c) 2008, IPython Development Team
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of
+conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list
+of conditions and the following disclaimer in the documentation and/or other
+materials provided with the distribution.
+
+Neither the name of the IPython Development Team nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+About the IPython Development Team
+----------------------------------
+
+Fernando Perez began IPython in 2001 based on code from Janko Hauser <[e-mail]> 
+and Nathaniel Gray <[e-mail]>.  Fernando is still the project lead.
+
+The IPython Development Team is the set of all contributors to the IPython project.
+This includes all of the IPython subprojects. Here is a list of the currently active contributors:
+
+	* Matthieu Brucher
+	* Ondrej Certik
+	* Laurent Dufrechou
+	* Robert Kern
+	* Brian E. Granger
+	* Fernando Perez (project leader)
+	* Benjamin Ragan-Kelley
+	* Ville M. Vainio
+	* Gael Varoququx
+	* Stefan van der Walt
+	* Tech-X Corporation
+	* Barry Wark
+
+If your name is missing, please add it.  
+
+Our Copyright Policy
+--------------------
+
+IPython uses a shared copyright model. Each contributor maintains copyright over
+their contributions to IPython. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the IPython
+source code, in its entirety is not the copyright of any single person or
+institution. Instead, it is the collective copyright of the entire IPython
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate their
+copyright in the commit message of the change, when they commit the change to
+one of the IPython repositories.
+
+With this in mind, the following banner should be used in any source code file to 
+indicate the copyright and license terms:
+
+#-------------------------------------------------------------------------------
+#  Copyright (C) 2008  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-------------------------------------------------------------------------------
  No newline at end of file

IPython/config/config.py

@@ -0,0 +1,179
+"""Load and store configuration objects.
+
+Test this module using
+
+nosetests -v --with-doctest --doctest-tests IPython.config
+
+"""
+
+from __future__ import with_statement
+from contextlib import contextmanager
+
+import inspect
+import types
+from IPython.config import traitlets
+from traitlets import Traitlet
+from IPython.external.configobj import ConfigObj
+
+def debug(s):
+    import sys
+    sys.stderr.write(str(s) + '\n')
+
+@contextmanager
+def raw(config):
+    """Context manager for accessing traitlets directly.
+
+    """
+    config.__getattribute__('',raw_access=True)
+    yield config
+    config.__getattribute__('',raw_access=False)
+
+class Config(object):
+    """
+    Implementation Notes
+    ====================
+    All instances of the same Config class share properties.  Therefore,
+
+    >>> class Sample(Config):
+    ...     my_float = traitlets.Float(3)
+
+    >>> s0 = Sample()
+    >>> s1 = Sample()
+    >>> s0.my_float = 5
+    >>> s0.my_float == s1.my_float
+    True
+
+    """
+    def __init__(self):
+        # Instantiate subconfigs
+        with raw(self):
+            subconfigs = [(n,v) for n,v in
+                          inspect.getmembers(self, inspect.isclass)
+                          if not n.startswith('__')]
+
+        for n,v in subconfigs:
+            setattr(self, n, v())
+
+    def __getattribute__(self,attr,raw_access=None,
+                         _ns={'raw_access':False}):
+        if raw_access is not None:
+            _ns['raw_access'] = raw_access
+            return
+
+        obj = object.__getattribute__(self,attr)
+        if isinstance(obj,Traitlet) and not _ns['raw_access']:
+            return obj.__call__()
+        else:
+            return obj
+
+    def __setattr__(self,attr,value):
+        obj = object.__getattribute__(self,attr)
+        if isinstance(obj,Traitlet):
+            obj(value)
+        else:
+            self.__dict__[attr] = value
+
+    def __str__(self,level=1,only_modified=True):
+        ci = ConfigInspector(self)
+        out = ''
+        spacer = '  '*(level-1)
+
+        # Add traitlet representations
+        for p,v in ci.properties:
+            if (v.modified and only_modified) or not only_modified:
+                out += spacer + '%s = %s\n' % (p,v)
+
+        # Add subconfig representations
+        for (n,v) in ci.subconfigs:
+            sub_str = v.__str__(level=level+1,only_modified=only_modified)
+            if sub_str:
+                out += '\n' + spacer + '[' * level + ('%s' % n) \
+                       + ']'*level + '\n'
+                out += sub_str
+
+        return out
+
+    def __iadd__(self,source):
+        """Load configuration from filename, and update self.
+
+        """
+        if not isinstance(source,dict):
+            source = ConfigObj(source, unrepr=True)
+        update_from_dict(self,source)
+        return self
+
+
+class ConfigInspector(object):
+    """Allow the inspection of Config objects.
+
+    """
+    def __init__(self,config):
+        self._config = config
+
+    @property
+    def properties(self):
+        "Return all traitlet names."
+        with raw(self._config):
+            return inspect.getmembers(self._config,
+                                      lambda obj: isinstance(obj, Traitlet))
+
+    @property
+    def subconfigs(self):
+        "Return all subconfig names and values."
+        with raw(self._config):
+            return [(n,v) for n,v in
+                    inspect.getmembers(self._config,
+                                       lambda obj: isinstance(obj,Config))
+                    if not n.startswith('__')]
+
+    def reset(self):
+        for (p,v) in self.properties:
+            v.reset()
+
+        for (s,v) in self.subconfigs:
+            ConfigInspector(v).reset()
+
+def update_from_dict(config,d):
+    """Propagate the values of the dictionary to the given configuration.
+
+    Useful to load configobj instances.
+
+    """
+    for k,v in d.items():
+        try:
+            prop_or_subconfig = getattr(config, k)
+        except AttributeError:
+            print "Invalid section/property in config file: %s" % k
+        else:
+            if isinstance(v,dict):
+                update_from_dict(prop_or_subconfig,v)
+            else:
+                setattr(config, k, v)
+
+def dict_from_config(config,only_modified=True):
+    """Create a dictionary from a Config object."""
+    ci = ConfigInspector(config)
+    out = {}
+
+    for p,v in ci.properties:
+        if (v.modified and only_modified) or not only_modified:
+            out[p] = v
+
+    for s,v in ci.subconfigs:
+        d = dict_from_config(v,only_modified)
+        if d != {}:
+            out[s] = d
+
+    return out
+
+def write(config, target):
+    """Write a configuration to file.
+
+    """
+    if isinstance(target, str):
+        target = open(target, 'w+')
+    target.flush()
+    target.seek(0)
+
+    confobj = ConfigObj(dict_from_config(config), unrepr=True)
+    confobj.write(target)

IPython/config/tests/sample_config.py

@@ -0,0 +1,19
+from IPython.config.api import *
+
+class SubSubSample(Config):
+    my_int = Int(3)
+
+
+class Sample(Config):
+    my_float = Float(3)
+    my_choice = Enum('a','b','c')
+
+    class MiddleSection(Config):
+        left_alone = Enum('1','2','c')
+        unknown_mod = Module('asd')
+
+    class SubSample(Config):
+        subsample_uri = URI('http://localhost:8080')
+
+        # Example of how to include external config
+        SubSubSample = SubSubSample()

IPython/config/tests/test_config.py

@@ -0,0 +1,135
+"""
+# Test utilities
+
+>>> import os
+
+>>> def dict_as_sorted_list(d):
+...     for k in d:
+...         if isinstance(d[k],dict):
+...             d[k] = dict_as_sorted_list(d[k])
+...     return sorted(d.items())
+
+>>> def pprint(d,level=0):
+...     if isinstance(d,dict):
+...         d = dict_as_sorted_list(d)
+...     for item,value in d:
+...         if isinstance(value,list):
+...             print "%s%s" % (' '*level, item)
+...             pprint(value,level+2)
+...         else:
+...             print "%s%s: %s" % (' '*level, item, value)
+
+
+# Tests
+
+>>> from IPython.config.api import *
+>>> from sample_config import *
+
+>>> s = Sample()
+>>> print s.my_float
+3.0
+>>> s.my_float = 4
+>>> print s.my_float
+4.0
+>>> print type(s.my_float)
+<type 'float'>
+>>> s.SubSample.SubSubSample.my_int = 5.0
+>>> print s.SubSample.SubSubSample.my_int
+5
+
+>>> i = ConfigInspector(s)
+>>> print i.properties
+[('my_choice', 'a'), ('my_float', 4.0)]
+>>> print tuple(s for s,v in i.subconfigs)
+('MiddleSection', 'SubSample')
+
+>>> print s
+my_float = 4.0
+<BLANKLINE>
+[SubSample]
+<BLANKLINE>
+  [[SubSubSample]]
+    my_int = 5
+<BLANKLINE>
+
+>>> import tempfile
+>>> fn = tempfile.mktemp()
+>>> f = open(fn,'w')
+>>> f.write(str(s))
+>>> f.close()
+
+>>> s += fn
+
+>>> from IPython.external.configobj import ConfigObj
+>>> c = ConfigObj(fn)
+>>> c['SubSample']['subsample_uri'] = 'http://ipython.scipy.org'
+
+>>> s += c
+>>> print s
+my_float = 4.0
+<BLANKLINE>
+[SubSample]
+  subsample_uri = 'http://ipython.scipy.org'
+<BLANKLINE>
+  [[SubSubSample]]
+    my_int = 5
+<BLANKLINE>
+
+>>> pprint(dict_from_config(s,only_modified=False))
+MiddleSection
+  left_alone: '1'
+  unknown_mod: 'asd'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_choice: 'a'
+my_float: 4.0
+
+>>> pprint(dict_from_config(s))
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+Test roundtripping:
+
+>>> fn = tempfile.mktemp()
+>>> f = open(fn, 'w')
+>>> f.write('''
+... [MiddleSection]
+... # some comment here
+... left_alone = 'c'
+... ''')
+>>> f.close()
+
+>>> s += fn
+
+>>> pprint(dict_from_config(s))
+MiddleSection
+  left_alone: 'c'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+>>> write(s, fn)
+>>> f = file(fn,'r')
+>>> ConfigInspector(s).reset()
+>>> pprint(dict_from_config(s))
+
+>>> s += fn
+>>> os.unlink(fn)
+>>> pprint(dict_from_config(s))
+MiddleSection
+  left_alone: 'c'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+
+"""

IPython/config/traitlets.py

@@ -0,0 +1,322
+"""Traitlets -- a light-weight meta-class free stand-in for Traits.
+
+Traitlet behaviour
+==================
+- Automatic casting, equivalent to traits.C* classes, e.g. CFloat, CBool etc.
+
+- By default, validation is done by attempting to cast a given value
+  to the underlying type, e.g. bool for Bool, float for Float etc.
+
+- To set or get a Traitlet value, use the ()-operator.  E.g.
+
+  >>> b = Bool(False)
+  >>> b(True)
+  >>> print b # returns a string representation of the Traitlet
+  True
+  >>> print b() # returns the underlying bool object
+  True
+
+  This makes it possible to change values "in-place", unlike an assigment
+  of the form
+
+  >>> c = Bool(False)
+  >>> c = True
+
+  which results in
+
+  >>> print type(b), type(c)
+  <class 'IPython.config.traitlets.Bool'> <type 'bool'>
+
+- Each Traitlet keeps track of its modification state, e.g.
+
+  >>> c = Bool(False)
+  >>> print c.modified
+  False
+  >>> c(False)
+  >>> print c.modified
+  False
+  >>> c(True)
+  >>> print c.modified
+  True
+
+How to customize Traitlets
+==========================
+
+The easiest way to create a new Traitlet is by wrapping an underlying
+Python type.  This is done by setting the "_type" class attribute.  For
+example, creating an int-like Traitlet is done as follows:
+
+>>> class MyInt(Traitlet):
+...     _type = int
+
+>>> i = MyInt(3)
+>>> i(4)
+>>> print i
+4
+
+>>> try:
+...     i('a')
+... except ValidationError:
+...    pass # this is expected
+... else:
+...     "This should not be reached."
+
+Furthermore, the following methods are provided for finer grained
+control of validation and assignment:
+
+ - validate(self,value)
+   Ensure that "value" is valid.  If not, raise an exception of any kind
+   with a suitable error message, which is reported to the user.
+
+ - prepare_value(self)
+   When using the ()-operator to query the underlying Traitlet value,
+   that value is first passed through prepare_value.  For example:
+
+   >>> class Eval(Traitlet):
+   ...     _type = str
+   ...
+   ...     def prepare_value(self):
+   ...         return eval(self._value)
+
+   >>> x = Eval('1+1')
+   >>> print x
+   '1+1'
+   >>> print x()
+   2
+
+ - __repr__(self)
+   By default, repr(self._value) is returned.  This can be customised
+   to, for example, first call prepare_value and return the repr of
+   the resulting object.
+
+"""
+
+import re
+import types
+
+class ValidationError(Exception):
+    pass
+
+class Traitlet(object):
+    """Traitlet which knows its modification state.
+
+    """
+    def __init__(self, value):
+        "Validate and store the default value.  State is 'unmodified'."
+        self._type = getattr(self,'_type',None)
+        value = self._parse_validation(value)
+        self._default_value = value
+        self.reset()
+
+    def reset(self):
+        self._value = self._default_value
+        self._changed = False
+
+    def validate(self, value):
+        "Validate the given value."
+        if self._type is not None:
+            self._type(value)
+
+    def _parse_validation(self, value):
+        """Run validation and return a descriptive error if needed.
+
+        """
+        try:
+            self.validate(value)
+        except Exception, e:
+            err_message = 'Cannot convert "%s" to %s' % \
+                          (value, self.__class__.__name__.lower())
+            if e.message:
+                err_message += ': %s' % e.message
+            raise ValidationError(err_message)
+        else:
+            # Cast to appropriate type before storing
+            if self._type is not None:
+                value = self._type(value)
+            return value
+
+    def prepare_value(self):
+        """Run on value before it is ever returned to the user.
+
+        """
+        return self._value
+
+    def __call__(self,value=None):
+        """Query or set value depending on whether `value` is specified.
+
+        """
+        if value is None:
+            return self.prepare_value()
+
+        self._value = self._parse_validation(value)
+        self._changed = (self._value != self._default_value)
+
+    @property
+    def modified(self):
+        "Whether value has changed from original definition."
+        return self._changed
+
+    def __repr__(self):
+        """This class is represented by the underlying repr.  Used when
+        dumping value to file.
+
+        """
+        return repr(self._value)
+
+class Float(Traitlet):
+    """
+    >>> f = Float(0)
+    >>> print f.modified
+    False
+
+    >>> f(3)
+    >>> print f()
+    3.0
+    >>> print f.modified
+    True
+
+    >>> f(0)
+    >>> print f()
+    0.0
+    >>> print f.modified
+    False
+
+    >>> try:
+    ...    f('a')
+    ... except ValidationError:
+    ...    pass
+
+    """
+    _type = float
+
+class Enum(Traitlet):
+    """
+    >>> c = Enum('a','b','c')
+    >>> print c()
+    a
+
+    >>> try:
+    ...    c('unknown')
+    ... except ValidationError:
+    ...    pass
+
+    >>> print c.modified
+    False
+
+    >>> c('b')
+    >>> print c()
+    b
+
+    """
+    def __init__(self, *options):
+        self._options = options
+        super(Enum,self).__init__(options[0])
+
+    def validate(self, value):
+        if not value in self._options:
+            raise ValueError('must be one of %s' % str(self._options))
+
+class Module(Traitlet):
+    """
+    >>> m = Module('some.unknown.module')
+    >>> print m
+    'some.unknown.module'
+
+    >>> m = Module('re')
+    >>> assert type(m()) is types.ModuleType
+
+    """
+    _type = str
+
+    def prepare_value(self):
+        try:
+            module = eval(self._value)
+        except:
+            module = None
+
+        if type(module) is not types.ModuleType:
+            raise ValueError("Invalid module name: %s" % self._value)
+        else:
+            return module
+
+
+class URI(Traitlet):
+    """
+    >>> u = URI('http://')
+
+    >>> try:
+    ...    u = URI('something.else')
+    ... except ValidationError:
+    ...    pass
+
+    >>> u = URI('http://ipython.scipy.org/')
+    >>> print u
+    'http://ipython.scipy.org/'
+
+    """
+    _regexp = re.compile(r'^[a-zA-Z]+:\/\/')
+    _type = str
+
+    def validate(self, uri):
+        if not self._regexp.match(uri):
+            raise ValueError()
+
+class Int(Traitlet):
+    """
+    >>> i = Int(3.5)
+    >>> print i
+    3
+    >>> print i()
+    3
+
+    >>> i = Int('4')
+    >>> print i
+    4
+
+    >>> try:
+    ...    i = Int('a')
+    ... except ValidationError:
+    ...    pass
+    ... else:
+    ...    raise "Should fail"
+
+    """
+    _type = int
+
+class Bool(Traitlet):
+    """
+    >>> b = Bool(2)
+    >>> print b
+    True
+    >>> print b()
+    True
+
+    >>> b = Bool('True')
+    >>> print b
+    True
+    >>> b(True)
+    >>> print b.modified
+    False
+
+    >>> print Bool(0)
+    False
+
+    """
+    _type = bool
+
+class Unicode(Traitlet):
+    """
+    >>> u = Unicode(123)
+    >>> print u
+    u'123'
+
+    >>> u = Unicode('123')
+    >>> print u.modified
+    False
+
+    >>> u('hello world')
+    >>> print u
+    u'hello world'
+
+    """
+    _type = unicode

README.txt

@@ -0,0 +1,11
+===============
+IPython1 README
+===============
+ 
+.. contents::
+
+Overview
+========
+
+Welcome to IPython.  New users should consult our documentation, which can be found
+in the docs/source subdirectory.

docs/Makefile

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

docs/source/changes.txt

@@ -0,0 +1,161
+.. _changes:
+
+==========
+What's new
+==========
+
+.. contents::
+
+Release 0.9
+===========
+
+New features
+------------
+
+	* All of the parallel computing capabilities from `ipython1-dev` have been merged into
+	  IPython proper.  This resulted in the following new subpackages:  
+	  :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
+	  :mod:`IPython.tools` and :mod:`IPython.testing`.
+	* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and friends
+	  have been completely refactored.  Now we are checking for dependencies using
+	  the approach that matplotlib uses.
+	* The documentation has been completely reorganized to accept the documentation
+	  from `ipython1-dev`.
+	* We have switched to using Foolscap for all of our network protocols in
+	  :mod:`IPython.kernel`.  This gives us secure connections that are both encrypted
+	  and authenticated.
+	* We have a brand new `COPYING.txt` files that describes the IPython license
+	  and copyright.  The biggest change is that we are putting "The IPython
+	  Development Team" as the copyright holder.  We give more details about exactly
+	  what this means in this file.  All developer should read this and use the new
+	  banner in all IPython source code files.
+
+Bug fixes
+---------
+
+	* A few subpackages has missing `__init__.py` files.
+	* The documentation is only created is Sphinx is found.  Previously, the `setup.py`
+	  script would fail if it was missing.
+
+Backwards incompatible changes
+------------------------------
+
+	* IPython has a larger set of dependencies if you want all of its capabilities.
+	  See the `setup.py` script for details.
+	* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
+	  :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
+	  Instead they take the filename of a file that contains the FURL for that
+	  client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
+	  and the constructor can be left empty.
+	* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
+	  using the factory functions :func:`get_multiengine_client` and 
+	  :func:`get_task_client`.  These return a `Deferred` to the actual client.
+	* The command line options to `ipcontroller` and `ipengine` have changed to
+	  reflect the new Foolscap network protocol and the FURL files.  Please see the
+	  help for these scripts for details.
+	* The configuration files for the kernel have changed because of the Foolscap stuff.
+	  If you were using custom config files before, you should delete them and regenerate
+	  new ones.
+
+Changes merged in from IPython1
+-------------------------------
+
+New features
+............
+
+	* Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted
+	  and zope.interface are now easy installable, we can declare them as dependencies
+	  in our setupegg.py script.
+	* IPython is now compatible with Twisted 2.5.0 and 8.x.
+	* Added a new example of how to use :mod:`ipython1.kernel.asynclient`.
+	* Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
+	  been merged into IPython and is still in `ipython1-dev`.
+	* The ``TaskController`` now has methods for getting the queue status.
+	* The ``TaskResult`` objects not have information about how long the task
+	  took to run.
+	* We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
+	  we use to carry additional info around.
+	* New top-level module :mod:`asyncclient` that has asynchronous versions (that
+	  return deferreds) of the client classes.  This is designed to users who want
+	  to run their own Twisted reactor
+	* All the clients in :mod:`client` are now based on Twisted.  This is done by 
+	  running the Twisted reactor in a separate thread and using the
+	  :func:`blockingCallFromThread` function that is in recent versions of Twisted.
+	* Functions can now be pushed/pulled to/from engines using
+	  :meth:`MultiEngineClient.push_function` and :meth:`MultiEngineClient.pull_function`.
+	* Gather/scatter are now implemented in the client to reduce the work load
+	  of the controller and improve performance.
+	* Complete rewrite of the IPython docuementation.  All of the documentation
+	  from the IPython website has been moved into docs/source as restructured
+	  text documents.  PDF and HTML documentation are being generated using 
+	  Sphinx.
+	* New developer oriented documentation: development guidelines and roadmap. 
+	* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt`` file
+	  that is organized by release and is meant to provide something more relevant
+	  for users.
+
+Bug fixes
+.........
+
+	* Created a proper ``MANIFEST.in`` file to create source distributions.
+	* Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
+	  actions were being collected with a :class:`DeferredList` with 
+	  ``fireononeerrback=1``.  This meant that methods were returning 
+	  before all engines had given their results.  This was causing extremely odd 
+	  bugs in certain cases. To fix this problem, we have 1) set 
+	  ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
+	  before returning and 2) introduced a :exc:`CompositeError` exception 
+	  that wraps all of the engine exceptions.  This is a huge change as it means 
+	  that users will have to catch :exc:`CompositeError` rather than the actual
+	  exception.
+
+Backwards incompatible changes
+..............................
+
+	* All names have been renamed to conform to the lowercase_with_underscore
+	  convention.  This will require users to change references to all names like
+	  ``queueStatus`` to ``queue_status``.
+	* Previously, methods like :meth:`MultiEngineClient.push` and    	
+	  :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was 
+	  becoming a problem as we weren't able to introduce new keyword arguments into
+	  the API.  Now these methods simple take a dict or sequence.  This has also allowed
+	  us to get rid of the ``*All`` methods like :meth:`pushAll` and :meth:`pullAll`.
+	  These things are now handled with the ``targets`` keyword argument that defaults
+	  to ``'all'``.
+	* The :attr:`MultiEngineClient.magicTargets` has been renamed to
+	  :attr:`MultiEngineClient.targets`. 
+	* All methods in the MultiEngine interface now accept the optional keyword argument
+	  ``block``.
+	* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
+	  :class:`TaskController` to :class:`TaskClient`.
+	* Renamed the top-level module from :mod:`api` to :mod:`client`.
+	* Most methods in the multiengine interface now raise a :exc:`CompositeError` exception
+	  that wraps the user's exceptions, rather than just raising the raw user's exception.
+	* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
+	  and ``pull``.
+
+Release 0.8.4
+=============
+
+Someone needs to describe what went into 0.8.4.
+
+Release 0.8.2
+=============
+
+* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
+  and jumps to /foo. The current behaviour is closer to the documented 
+  behaviour, and should not trip anyone.
+  
+Release 0.8.3
+=============
+  
+* pydb is now disabled by default (due to %run -d problems). You can enable
+  it by passing -pydb command line argument to IPython. Note that setting
+  it in config file won't work.
+
+Older releases
+==============
+
+Changes in earlier releases of IPython are described in the older file ``ChangeLog``.  
+Please refer to this document for details.
+

docs/source/config/customization.txt

@@ -0,0 +1,284
+.. _customization:
+
+========================
+Customization of IPython
+========================
+
+There are 2 ways to configure IPython - the old way of using ipythonrc
+files (an INI-file like format), and the new way that involves editing
+your ipy_user_conf.py. Both configuration systems work at the same
+time, so you can set your options in both, but if you are hesitating
+about which alternative to choose, we recommend the ipy_user_conf.py
+approach, as it will give you more power and control in the long
+run. However, there are few options such as pylab_import_all that can
+only be specified in ipythonrc file or command line - the reason for
+this is that they are needed before IPython has been started up, and
+the IPApi object used in ipy_user_conf.py is not yet available at that
+time. A hybrid approach of specifying a few options in ipythonrc and
+doing the more advanced configuration in ipy_user_conf.py is also
+possible.
+
+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.
+
+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.
  No newline at end of file

docs/source/config/index.txt

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

docs/source/config/initial_config.txt

@@ -0,0 +1,238
+.. _initial config:
+
+=========================================
+Initial configuration of your environment
+=========================================
+
+This section will help you set various things in your environment for
+your IPython sessions to be as efficient as possible. All of IPython's
+configuration information, along with several example files, is stored
+in a directory named by default $HOME/.ipython. You can change this by
+defining the environment variable IPYTHONDIR, or at runtime with the
+command line option -ipythondir.
+
+If all goes well, the first time you run IPython it should
+automatically create a user copy of the config directory for you,
+based on its builtin defaults. You can look at the files it creates to
+learn more about configuring the system. The main file you will modify
+to configure IPython's behavior is called ipythonrc (with a .ini
+extension under Windows), included for reference in `ipythonrc`_ 
+section. This file is very commented and has many variables you can
+change to suit your taste, you can find more details in
+Sec. customization_. Here we discuss the basic things you will want to
+make sure things are working properly from the beginning.
+
+
+.. _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).
  No newline at end of file

docs/source/config/new_config.txt

@@ -0,0 +1,27
+========================
+New configuration system
+========================
+
+IPython has a configuration system. When running IPython for the first time,
+reasonable defaults are used for the configuration. The configuration of IPython
+can be changed in two ways:
+
+	* Configuration files
+	* Commands line options (which override the configuration files)
+
+IPython has a separate configuration file for each subpackage. Thus, the main
+configuration files are (in your ``~/.ipython`` directory):
+
+ 	* ``ipython1.core.ini``
+	* ``ipython1.kernel.ini``
+	* ``ipython1.notebook.ini``
+
+To create these files for the first time, do the following::
+
+	from ipython1.kernel.config import config_manager as kernel_config
+	kernel_config.write_default_config_file()
+
+But, you should only need to do this if you need to modify the defaults. If needed
+repeat this process with the ``notebook`` and ``core`` configuration as well. If you
+are running into problems with IPython, you might try deleting these configuration
+files.
  No newline at end of file

docs/source/credits.txt

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

docs/source/development/development.txt

@@ -0,0 +1,315
+.. _development:
+
+==================================
+IPython development guidelines
+==================================
+
+.. contents::
+..
+    1  Overview
+    2  Project organization
+      2.1  Subpackages
+      2.2  Installation and dependencies
+      2.3  Specific subpackages
+    3  Version control
+    4  Documentation
+      4.1  Standalone documentation
+      4.2  Docstring format
+    5  Coding conventions
+      5.1  General
+      5.2  Naming conventions
+    6  Testing
+    7  Configuration
+..
+
+
+Overview
+========
+
+IPython is the next generation of IPython.  It is named such for two reasons:
+
+- Eventually, IPython will become IPython version 1.0.
+- This new code base needs to be able to co-exist with the existing IPython until
+  it is a full replacement for it.  Thus we needed a different name.  We couldn't
+  use ``ipython`` (lowercase) as some files systems are case insensitive.
+
+There are two, no three, main goals of the IPython effort:
+
+1. Clean up the existing codebase and write lots of tests.
+2. Separate the core functionality of IPython from the terminal to enable IPython
+   to be used from within a variety of GUI applications.
+3. Implement a system for interactive parallel computing.
+
+While the third goal may seem a bit unrelated to the main focus of IPython, it turns
+out that the technologies required for this goal are nearly identical with those
+required for goal two. This is the main reason the interactive parallel computing
+capabilities are being put into IPython proper. Currently the third of these goals is
+furthest along.
+
+This document describes IPython from the perspective of developers.  
+
+
+Project organization
+====================
+
+Subpackages
+-----------
+
+IPython is organized into semi self-contained subpackages.  Each of the subpackages will have its own:
+
+- **Dependencies**.  One of the most important things to keep in mind in
+  partitioning code amongst subpackages, is that they should be used to cleanly
+  encapsulate dependencies.  
+- **Tests**.  Each subpackage shoud have its own ``tests`` subdirectory that
+  contains all of the tests for that package.  For information about writing tests
+  for IPython, see the `Testing System`_ section of this document.
+- **Configuration**.  Each subpackage should have its own ``config`` subdirectory
+  that contains the configuration information for the components of the 
+  subpackage.  For information about how the IPython configuration system
+  works, see the `Configuration System`_ section of this document.
+- **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory that
+  contains all of the command line scripts associated with the subpackage.
+
+Installation and dependencies
+-----------------------------
+   
+IPython will not use `setuptools`_ for installation. Instead, we will use standard
+``setup.py`` scripts that use `distutils`_. While there are a number a extremely nice
+features that `setuptools`_ has (like namespace packages), the current implementation
+of `setuptools`_ has performance problems, particularly on shared file systems. In
+particular, when Python packages are installed on NSF file systems, import times
+become much too long (up towards 10 seconds). 
+
+Because IPython is being used extensively in the context of high performance
+computing, where performance is critical but shared file systems are common, we feel
+these performance hits are not acceptable. Thus, until the performance problems
+associated with `setuptools`_ are addressed, we will stick with plain `distutils`_. We
+are hopeful that these problems will be addressed and that we will eventually begin
+using `setuptools`_. Because of this, we are trying to organize IPython in a way that
+will make the eventual transition to `setuptools`_ as painless as possible.
+
+Because we will be using `distutils`_, there will be no method for automatically installing dependencies.  Instead, we are following the approach of `Matplotlib`_ which can be summarized as follows:
+
+- Distinguish between required and optional dependencies.  However, the required
+  dependencies for IPython should be only the Python standard library.
+- Upon installation check to see which optional dependencies are present and tell
+  the user which parts of IPython need which optional dependencies.
+
+It is absolutely critical that each subpackage of IPython has a clearly specified set
+of dependencies and that dependencies are not carelessly inherited from other IPython
+subpackages. Furthermore, tests that have certain dependencies should not fail if
+those dependencies are not present. Instead they should be skipped and print a
+message.
+
+.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+.. _distutils: http://docs.python.org/lib/module-distutils.html
+.. _Matplotlib: http://matplotlib.sourceforge.net/
+
+Specific subpackages
+--------------------
+
+``core``
+	This is the core functionality of IPython that is independent of the
+	terminal, network and GUIs.  Most of the code that is in the current
+	IPython trunk will be refactored, cleaned up and moved here.
+
+``kernel``
+	The enables the IPython core to be expose to a the network.  This is
+	also where all of the parallel computing capabilities are to be found.
+	
+``config``
+	The configuration package used by IPython.
+
+``frontends``
+	The various frontends for IPython.  A frontend is the end-user application
+	that exposes the capabilities of IPython to the user.  The most basic frontend
+	will simply be a terminal based application that looks just like today 's 
+	IPython.  Other frontends will likely be more powerful and based on GUI toolkits.
+
+``notebook``
+	An application that allows users to work with IPython notebooks.
+
+``tools``
+	This is where general utilities go.
+
+
+Version control
+===============
+
+In the past, IPython development has been done using `Subversion`__.  We are currently trying out `Bazaar`__ and `Launchpad`__.
+
+.. __: http://subversion.tigris.org/
+.. __: http://bazaar-vcs.org/
+.. __: http://www.launchpad.net/ipython
+
+Documentation
+=============
+
+Standalone documentation
+------------------------
+
+All standalone documentation should be written in plain text (``.txt``) files using
+`reStructuredText`_ for markup and formatting. All such documentation should be placed
+in the top level directory ``docs`` of the IPython source tree. Or, when appropriate,
+a suitably named subdirectory should be used. The documentation in this location will
+serve as the main source for IPython documentation and all existing documentation
+should be converted to this format.
+
+In the future, the text files in the ``docs`` directory will be used to generate all
+forms of documentation for IPython. This include documentation on the IPython website
+as well as *pdf* documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+Docstring format
+----------------
+
+Good docstrings are very important. All new code will use `Epydoc`_ for generating API
+docs, so we will follow the `Epydoc`_ conventions. More specifically, we will use
+`reStructuredText`_ for markup and formatting, since it is understood by a wide
+variety of tools. This means that if in the future we have any reason to change from
+`Epydoc`_ to something else, we'll have fewer transition pains.
+
+Details about using `reStructuredText`_ for docstrings can be found `here
+<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+
+.. _Epydoc: http://epydoc.sourceforge.net/
+
+Additional PEPs of interest regarding documentation of code:
+
+- `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
+- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
+- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+
+
+Coding conventions
+==================
+
+General
+-------
+
+In general, we'll try to follow the standard Python style conventions as described here:
+
+- `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
+
+
+Other comments:
+
+- In a large file, top level classes and functions should be 
+  separated by 2-3 lines to make it easier to separate them visually.
+- Use 4 spaces for indentation.
+- Keep the ordering of methods the same in classes that have the same 
+  methods.  This is particularly true for classes that implement 
+  similar interfaces and for interfaces that are similar.
+
+Naming conventions
+------------------
+
+In terms of naming conventions, we'll follow the guidelines from the `Style Guide for
+Python Code`_.
+
+For all new IPython code (and much existing code is being refactored), we'll use:
+
+- All ``lowercase`` module names.
+
+- ``CamelCase`` for class names.
+
+- ``lowercase_with_underscores`` for methods, functions, variables and attributes.
+
+This may be confusing as most of the existing IPython codebase uses a different convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will move IPython over to the new
+convention, providing shadow names for backward compatibility in public interfaces. 
+
+There are, however, some important exceptions to these rules.  In some cases, IPython
+code will interface with packages (Twisted, Wx, Qt) that use other conventions.  At some level this makes it impossible to adhere to our own standards at all times.  In particular, when subclassing classes that use other naming conventions, you must follow their naming conventions.  To deal with cases like this, we propose the following policy:
+
+- If you are subclassing a class that uses different conventions, use its
+  naming conventions throughout your subclass.  Thus, if you are creating a 
+  Twisted Protocol class, used Twisted's ``namingSchemeForMethodsAndAttributes.``
+
+- All IPython's official interfaces should use our conventions.  In some cases 
+  this will mean that you need to provide shadow names (first implement ``fooBar``
+  and then ``foo_bar = fooBar``).  We want to avoid this at all costs, but it 
+  will probably be necessary at times.  But, please use this sparingly!
+
+Implementation-specific *private* methods will use ``_single_underscore_prefix``.
+Names with a leading double underscore will *only* be used in special cases, as they
+makes subclassing difficult (such names are not easily seen by child classes).
+
+Occasionally some run-in lowercase names are used, but mostly for very short names or
+where we are implementing methods very similar to existing ones in a base class (like
+``runlines()`` where ``runsource()`` and ``runcode()`` had established precedent).
+
+The old IPython codebase has a big mix of classes and modules prefixed with an
+explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned upon, as
+namespaces offer cleaner prefixing. The only case where this approach is justified is
+for classes which are expected to be imported into external namespaces and a very
+generic name (like Shell) is too likely to clash with something else. We'll need to
+revisit this issue as we clean up and refactor the code, but in general we should
+remove as many unnecessary ``IP``/``ip`` prefixes as possible. However, if a prefix
+seems absolutely necessary the more specific ``IPY`` or ``ipy`` are preferred.
+
+.. _devel_testing:
+
+Testing system
+==============
+
+It is extremely important that all code contributed to IPython has tests. Tests should
+be written as unittests, doctests or as entities that the `Nose`_ testing package will
+find. Regardless of how the tests are written, we will use `Nose`_ for discovering and
+running the tests. `Nose`_ will be required to run the IPython test suite, but will
+not be required to simply use IPython.
+
+.. _Nose: http://code.google.com/p/python-nose/
+
+Tests of `Twisted`__ using code should be written by subclassing the ``TestCase`` class
+that comes with ``twisted.trial.unittest``. When this is done, `Nose`_ will be able to
+run the tests and the twisted reactor will be handled correctly.
+
+.. __: http://www.twistedmatrix.com
+
+Each subpackage in IPython should have its own ``tests`` directory that contains all
+of the tests for that subpackage. This allows each subpackage to be self-contained. If
+a subpackage has any dependencies beyond the Python standard library, the tests for
+that subpackage should be skipped if the dependencies are not found. This is very
+important so users don't get tests failing simply because they don't have dependencies.
+
+We also need to look into use Noses ability to tag tests to allow a more modular
+approach of running tests.
+
+.. _devel_config:
+
+Configuration system
+====================
+
+IPython uses `.ini`_ files for configuration purposes. This represents a huge
+improvement over the configuration system used in IPython. IPython works with these
+files using the `ConfigObj`_ package, which IPython includes as
+``ipython1/external/configobj.py``.
+
+Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of IPython
+should contain a ``config`` subdirectory that contains all of the configuration
+information for the subpackage. To see how configuration information is defined (along
+with defaults) see at the examples in ``ipython1/kernel/config`` and
+``ipython1/core/config``. Likewise, to see how the configuration information is used,
+see examples in ``ipython1/kernel/scripts/ipengine.py``.
+
+Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We are
+calling this new layer, ``tconfig``, as it will use a `Traits`_-like validation model.
+We won't actually use `Traits`_, but will implement something similar in pure Python.
+But, even in this new system, we will still use `ConfigObj`_ and `.ini`_ files
+underneath the hood. Talk to Fernando if you are interested in working on this part of
+IPython. The current prototype of ``tconfig`` is located in the IPython sandbox.
+
+.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
+.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
+.. _Traits: http://code.enthought.com/traits/
+
+
+
+
+
+
+
+
+
+

docs/source/development/index.txt

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

docs/source/development/roadmap.txt

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

docs/source/faq.txt

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

docs/source/history.txt

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

docs/source/index.txt

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

docs/source/install/advanced.txt

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

docs/source/install/basic.txt

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

docs/source/install/index.txt

@@ -0,0 +1,9
+==================
+Installation
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   basic.txt
+   advanced.txt

docs/source/interactive/extension_api.txt

@@ -0,0 +1,252
+=====================
+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
  No newline at end of file

docs/source/interactive/index.txt

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

IPython/config/api.py

@@ -19,6 +19,11 import os
 from IPython.config.cutils import get_home_dir, get_ipython_dir
 from IPython.external.configobj import ConfigObj
 
+# Traitlets config imports
+from IPython.config import traitlets
+from IPython.config.config import *
+from traitlets import *
+
 class ConfigObjManager(object):
     
     def __init__(self, configObj, filename):

MANIFEST.in

@@ -13,20 +13,15 graft IPython/config
 graft IPython/testing
 graft IPython/tools
 
-graft doc
-exclude doc/\#*
-exclude doc/*.1
-exclude doc/ChangeLog.*
-exclude doc/update_version.sh
+graft docs
+exclude docs/\#*
+exclude docs/man/*.1
+exclude docs/ChangeLog.*
 
 # 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/*
+exclude docs/attic/*
+exclude docs/build/*
 
 global-exclude *~
 global-exclude *.flc

docs/source/conf.py

@@ -1,7 +1,7
 # -*- coding: utf-8 -*-
 #
 # IPython documentation build configuration file, created by
-# sphinx-quickstart.py on Sat Mar 29 15:36:13 2008.
+# sphinx-quickstart on Thu May  8 16:45:02 2008.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
@@ -11,38 +11,40
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
-import sys
+import sys, os
 
-# If your extensions are in another directory, add it here.
-#sys.path.append('some/directory')
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
 
 # 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.
+# coming with Sphinx (named 'sphinx.ext.*') 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'
+source_suffix = '.txt'
 
 # The master toctree document.
-master_doc = 'ipython'
+master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
-copyright = '2008, Fernando Perez'
+copyright = '2008, The IPython Development Team'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '0.8.3'
+version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.3'
+release = '0.9'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -53,6 +55,10 today_fmt = '%B %d, %Y'
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
+# List of directories, relative to source directories, that shouldn't be searched
+# for source files.
+#exclude_dirs = []
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
@@ -76,6 +82,14 pygments_style = 'sphinx'
 # given in html_static_path.
 html_style = 'default.css'
 
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = None
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -89,9 +103,6 html_last_updated_fmt = '%b %d, %Y'
 # 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 = {}
 
@@ -105,6 +116,14 html_last_updated_fmt = '%b %d, %Y'
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'IPythondoc'
 
@@ -113,14 +132,24 htmlhelp_basename = 'IPythondoc'
 # ------------------------
 
 # The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
+latex_paper_size = 'letter'
 
 # 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')]
+latex_documents = [
+  ('index', 'IPython.tex', 'IPython Documentation', 'The IPython Development Team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''