Work on documentation.

* Reorganizing material everywhere.
* Consolidating material in config and development.  We had lots of
  repeated material in development.
* Removing or fixing outdated or incorrect material.

docs/source/development/contributing.txt

@@ -0,0 +1,191 b''
+How to contribute to IPython
+============================
+
+IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
+This makes it easy for people to contribute to the development of IPython.
+There are several ways in which you can join in.
+
+If you have a small change that you want to send to the team, you can edit your
+bazaar checkout of IPython (see below) in-place, and ask bazaar for the
+differences::
+
+    $ cd /path/to/your/copy/of/ipython
+    $ bzr diff > my_fixes.diff
+
+This produces a patch file with your fixes, which we can apply to the source
+tree.  This file should then be attached to a ticket in our `bug tracker
+<https://bugs.launchpad.net/ipython>`_, indicating what it does.
+
+This model of creating small, self-contained patches works very well and there
+are open source projects that do their entire development this way.  However,
+in IPython we have found that for tracking larger changes, making use of
+bazaar's full capabilities in conjunction with Launchpad's code hosting
+services makes for a much better experience.
+
+Making your own branch of IPython allows you to refine your changes over time,
+track the development of the main team, and propose your own full version of
+the code for others to use and review, with a minimum amount of fuss.  The next
+parts of this document will explain how to do this.
+
+Install Bazaar and create a Launchpad account
+---------------------------------------------
+
+First make sure you have installed Bazaar (see their `website
+<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
+you, try the following::
+
+    $ bzr whoami
+    Joe Coder <[e-mail]>
+
+This should display your name and email. Next, you will want to create an
+account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
+ssh keys. For more information of setting up your ssh keys, see `this link
+<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
+
+Get the main IPython branch from Launchpad
+------------------------------------------
+
+Now, you can get a copy of the main IPython development branch (we call this
+the "trunk")::
+
+    $ bzr branch lp:ipython
+
+Create a working branch
+-----------------------
+
+When working on IPython, you won't actually make edits directly to the
+:file:`lp:ipython` branch. Instead, you will create a separate branch for your
+changes. For now, let's assume you want to do your work in a branch named
+"ipython-mybranch". Create this branch by doing::
+
+    $ bzr branch ipython ipython-mybranch
+
+When you actually create a branch, you will want to give it a name that
+reflects the nature of the work that you will be doing in it, like
+"install-docs-update".
+
+Make edits in your working branch
+---------------------------------
+
+Now you are ready to actually make edits in your :file:`ipython-mybranch`
+branch. Before doing this, it is helpful to install this branch so you can
+test your changes as you work. This is easiest if you have setuptools
+installed. Then, just do::
+
+    $ cd ipython-mybranch
+    $ python setupegg.py develop
+
+Now, make some changes. After a while, you will want to commit your changes.
+This let's Bazaar know that you like the changes you have made and gives you
+an opportunity to keep a nice record of what you have done. This looks like
+this::
+
+    $ ...do work in ipython-mybranch...
+    $ bzr commit -m "the commit message goes here"
+
+Please note that since we now don't use an old-style linear ChangeLog (that
+tends to cause problems with distributed version control systems), you should
+ensure that your log messages are reasonably detailed.  Use a docstring-like
+approach in the commit messages (including the second line being left
+*blank*)::
+
+  Single line summary of  changes being committed.
+
+  * more details when warranted ...
+  * including crediting outside contributors if they sent the
+    code/bug/idea!
+
+As you work, you will repeat this edit/commit cycle many times. If you work on
+your branch for a long time, you will also want to get the latest changes from
+the :file:`lp:ipython` branch. This can be done with the following sequence of
+commands::
+
+    $ ls
+    ipython
+    ipython-mybranch
+    
+    $ cd ipython
+    $ bzr pull
+    $ cd ../ipython-mybranch
+    $ bzr merge ../ipython
+    $ bzr commit -m "Merging changes from trunk"
+
+Along the way, you should also run the IPython test suite.  You can do this
+using the :command:`iptest` command (which is basically a customized version of
+:command:`nosetests`)::
+
+    $ cd
+    $ iptest
+
+The :command:`iptest` command will also pick up and run any tests you have
+written. See :ref:`testing documentation <devel_testing>` for further details
+on the testing system.
+
+
+Post your branch and request a code review
+------------------------------------------
+
+Once you are done with your edits, you should post your branch on Launchpad so
+that other IPython developers can review the changes and help you merge your
+changes into the main development branch. To post your branch on Launchpad,
+do::
+
+    $ cd ipython-mybranch
+    $ bzr push lp:~yourusername/ipython/ipython-mybranch
+
+Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
+should see your branch under the "Code" tab. If you click on your branch, you
+can provide a short description of the branch as well as mark its status. Most
+importantly, you should click the link that reads "Propose for merging into
+another branch". What does this do?
+
+This let's the other IPython developers know that your branch is ready to be
+reviewed and merged into the main development branch. During this review
+process, other developers will give you feedback and help you get your code
+ready to be merged. What types of things will we be looking for:
+
+* All code is documented.
+* All code has tests.
+* The entire IPython test suite passes.
+
+Once your changes have been reviewed and approved, someone will merge them
+into the main development branch.
+
+
+Some notes for core developers when merging third-party contributions
+=====================================================================
+
+Core developers, who ultimately merge any approved branch (from themselves,
+another developer, or any third-party contribution) will typically use
+:command:`bzr merge` to merge the branch into the trunk and push it to the
+main Launcphad site. This is a short list of things to keep in mind when doing
+this process, so that the project history is easy to understand in the long
+run, and that generating release notes is as painless and accurate as
+possible.
+
+- When you merge any non-trivial functionality (from one small bug fix to a
+  big feature branch), please remember to always edit the :file:`changes.txt`
+  file accordingly. This file has one main section for each release, and if
+  you edit it as you go, noting what new features, bug fixes or API changes
+  you have made, the release notes will be almost finished when they are
+  needed later. This is much easier if done when you merge the work, rather
+  than weeks or months later by re-reading a massive Bazaar log.
+
+- When big merges are done, the practice of putting a summary commit message
+  in the merge is *extremely* useful. It makes this kind of job much nicer,
+  because that summary log message can be almost copy/pasted without changes,
+  if it was well written, rather than dissecting the next-level messages from
+  the individual commits.
+
+- It's important that we remember to always credit who gave us something if
+  it's not the committer. In general, we have been fairly good on this front,
+  this is just a reminder to keep things up. As a note, if you are ever
+  committing something that is completely (or almost so) a third-party
+  contribution, do the commit as::
+
+    $ bzr commit --author="Someone Else"
+
+  This way it will show that name separately in the log, which makes it even
+  easier to spot. Obviously we often rework third party contributions
+  extensively, but this is still good to keep in mind for cases when we don't
+  touch the code too much.
  No newline at end of file

docs/source/development/release.txt

@@ -0,0 +1,25 b''
+Release checklist
+=================
+
+Most of the release process is automated by the :file:`release` script in the
+:file:`tools` directory.  This is just a handy reminder for the release manager.
+
+#. First, run :file:`build_release`, which does all the file checking and
+   building that the real release script will do.  This will let you do test
+   installations, check that the build procedure runs OK, etc.  You may want to
+   disable a few things like multi-version RPM building while testing, because
+   otherwise the build takes really long.
+
+#. Run the release script, which makes the tar.gz, eggs and Win32 .exe
+   installer.  It posts them to the site and registers the release with PyPI.
+
+#. Updating the website with announcements and links to the updated
+   changes.txt in html form. Remember to put a short note both on the news
+   page of the site and on Launcphad.
+
+#. Drafting a short release announcement with i) highlights and ii) a link to
+   the html changes.txt.
+
+#. Make sure that the released version of the docs is live on the site.
+
+#. Celebrate!
  No newline at end of file

docs/source/development/testing.txt

@@ -0,0 +1,194 b''
+.. _testing:
+
+=========================
+Writing and running tests
+=========================
+
+Overview
+========
+
+It is extremely important that all code contributed to IPython has tests.
+Tests should be written as unittests, doctests or other entities that the
+IPython test system can detect.  See below for more details on this.
+
+Each subpackage in IPython should have its own :file:`tests` directory that
+contains all of the tests for that subpackage. All of the files in the
+:file:`tests` directory should have the word "tests" in them to enable
+the testing framework to find them.  
+
+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 are still figuring out the best way for this
+to be handled.
+
+Status
+======
+
+Currently IPython's testing system is being reworked.  In the meantime,
+we recommend the following testing practices:
+
+* To run regular tests, use the :cmd:`nosetests` command on a per file basis:
+
+.. code-block:: bash
+
+    nosetests -vvs IPython.core.tests.test_component
+
+* To run Twisted-using tests, use the :cmd:`trial` command on a per file 
+  basis:
+
+.. code-block:: bash
+
+    trial IPython.kernel
+
+* For now, regular tests (of non-Twisted using code) should be written as
+  unit tests.  They should be subclasses of :class:`unittest.TestCase`.
+
+* Tests of Twisted [Twisted]_ using code should be written by subclassing the
+  ``TestCase`` class that comes with ``twisted.trial.unittest``.
+
+.. _devel_testing:
+
+Older material
+==============
+
+It is extremely important that all code contributed to IPython has tests.
+Tests should be written as unittests, doctests or as entities that the Nose
+[Nose]_ testing package will find. Regardless of how the tests are written, we
+will use Nose for discovering and running the tests. Nose will be required to
+run the IPython test suite, but will not be required to simply use IPython.
+
+Tests of Twisted using code need to follow two additional guidelines:
+
+1. Twisted using tests should be written by subclassing the :class:`TestCase`
+   class that comes with :mod:`twisted.trial.unittest`. 
+
+2. All :class:`Deferred` instances that are created in the test must be
+   properly chained and the final one *must* be the return value of the test
+   method.
+
+When these two things are done, Nose will be able to run the tests and the
+twisted reactor will be handled correctly.
+
+Each subpackage in IPython should have its own :file:`tests` directory that
+contains all of the tests for that subpackage. This allows each subpackage to
+be self-contained.  A good convention to follow is to have a file named
+:file:`test_foo.py` for each module :file:`foo.py` in the package.  This makes
+it easy to organize the tests, though like most conventions, it's OK to break
+it if logic and common sense dictate otherwise.
+
+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 ship a set of decorators in the
+:mod:`IPython.testing` package to tag tests that may be platform-specific or
+otherwise may have restrictions; if the existing ones don't fit your needs, add
+a new decorator in that location so other tests can reuse it.
+
+To run the IPython test suite, use the :command:`iptest` command that is
+installed with IPython (if you are using IPython in-place, without installing
+it, you can find this script in the :file:`scripts` directory)::
+
+    $ iptest
+
+This command colects all IPython tests into separate groups, and then calls
+either Nose with the proper options and extensions, or Twisted's
+:command:`trial`.  This ensures that tests that need the Twisted reactor
+management facilities execute separate of Nose.  If any individual test group
+fails, :command:`iptest` will print what you need to type so you can rerun that
+particular test group alone for debugging.
+
+By default, :command:`iptest` runs the entire IPython test
+suite (skipping tests that may be platform-specific or which depend on tools
+you may not have).  But you can also use it to run only one specific test file,
+or a specific test function.  For example, this will run only the
+:file:`test_magic` file from the test suite::
+
+    $ iptest IPython.tests.test_magic
+    ----------------------------------------------------------------------
+    Ran 10 tests in 0.348s
+
+    OK (SKIP=3)
+    Deleting object: second_pass
+
+while the ``path:function`` syntax allows you to select a specific function in
+that file to run::
+
+    $ iptest IPython.tests.test_magic:test_obj_del
+    ----------------------------------------------------------------------
+    Ran 1 test in 0.204s
+
+    OK
+
+Since :command:`iptest` is based on nosetests, you can pass it any regular
+nosetests option.  For example, you can use ``--pdb`` or ``--pdb-failures`` to
+automatically activate the interactive Pdb debugger on errors or failures.  See
+the nosetests documentation for further details.
+
+
+A few tips for writing tests
+----------------------------
+
+You can write tests either as normal test files, using all the conventions that
+Nose recognizes, or as doctests.  Note that *all* IPython functions should have
+at least one example that serves as a doctest, whenever technically feasible.
+However, example doctests should only be in the main docstring if they are *a
+good example*, i.e. if they convey useful information about the function.  If
+you simply would like to write a test as a doctest, put it in a separate test
+file and write a no-op function whose only purpose is its docstring.
+
+Note, however, that in a file named :file:`test_X`, functions whose only test
+is their docstring (as a doctest) and which have no test functionality of their
+own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
+double-counted (the empty function call is counted as a test, which just
+inflates tests numbers artificially).  This restriction does not apply to
+functions in files with other names, due to how Nose discovers tests.
+
+You can use IPython examples in your docstrings.  Those can make full use of
+IPython functionality (magics, variable substitution, etc), but be careful to
+keep them generic enough that they run identically on all Operating Systems.
+
+The prompts in your doctests can be either of the plain Python ``>>>`` variety
+or ``In [1]:`` IPython style.  Since this is the IPython system, after all, we
+encourage you to use IPython prompts throughout, unless you are illustrating a
+specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
+
+If a test isn't safe to run inside the main nose process (e.g. because it loads
+a GUI toolkit), consider running it in a subprocess and capturing its output
+for evaluation and test decision later.  Here is an example of how to do it, by
+relying on the builtin ``_ip`` object that contains the public IPython api as
+defined in :mod:`IPython.ipapi`::
+
+   def test_obj_del():
+       """Test that object's __del__ methods are called on exit."""
+       test_dir = os.path.dirname(__file__)
+       del_file = os.path.join(test_dir,'obj_del.py')
+       out = _ip.IP.getoutput('ipython %s' % del_file)
+       nt.assert_equals(out,'object A deleted')
+
+
+
+If a doctest contains input whose output you don't want to verify identically
+via doctest (random output, an object id, etc), you can mark a docstring with
+``#random``.  All of these test will have their code executed but no output
+checking will be done::
+
+       >>> 1+3
+       junk goes here...  # random
+
+       >>> 1+2
+       again,  anything goes #random
+       if multiline, the random mark is only needed once.
+
+       >>> 1+2
+       You can also put the random marker at the end:
+       # random
+
+       >>> 1+2
+       # random
+       .. or at the beginning.
+
+In a case where you want an *entire* docstring to be executed but not verified
+(this only serves to check that the code runs without crashing, so it should be
+used very sparingly), you can put ``# all-random`` in the docstring.
+

docs/source/about/credits.txt

@@ -1,208 +1,209 b''
 .. _credits:
 
 =======
 Credits
 =======
 
-IPython is led by Fernando Pérez.
+IPython was started and continues to be led by Fernando Pérez.
 
-As of this writing, the following developers have joined the core team:
+Core developers
+===============
 
-* [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>.
+As of this writing, core development team consists of the following
+developers:
 
-* [Brian Granger] <ellisonbg-AT-gmail.com>: extending IPython to allow
-  support for interactive parallel computing.
+* **Fernando Pérez** <Fernando.Perez-AT-berkeley.edu> Project creator and leader, 
+  IPython core, parallel computing infrastructure, testing, release manager.
 
-* [Benjamin (Min) Ragan-Kelley]: key work on IPython's parallel
-  computing infrastructure.
+* **Robert Kern** <rkern-AT-enthought.com> Co-mentored the 2005 Google Summer of
+  Code project, work on IPython's core.
 
-* [Ville Vainio] <vivainio-AT-gmail.com>: Ville has made many improvements
-  to the core of IPython and was the maintainer of the main IPython
-  trunk from version 0.7.1 to 0.8.4.
+* **Brian Granger** <ellisonbg-AT-gmail.com> Parallel computing 
+  infrastructure, IPython core.
 
-* [Gael Varoquaux] <gael.varoquaux-AT-normalesup.org>: work on the merged
-  architecture for the interpreter as of version 0.9, implementing a new WX GUI
-  based on this system.
+* **Benjamin (Min) Ragan-Kelley** <benjaminrk-AT-gmail.com> Parallel computing
+  infrastructure.
 
-* [Barry Wark] <barrywark-AT-gmail.com>: implementing a new Cocoa GUI, as well
-  as work on the new interpreter architecture and Twisted support.
+* **Ville Vainio** <vivainio-AT-gmail.com> IPython core, maintainer of IPython
+  trunk from version 0.7.2 to 0.8.4.
 
-* [Laurent Dufrechou] <laurent.dufrechou-AT-gmail.com>: development of the WX
-  GUI support.
+* **Gael Varoquaux** <gael.varoquaux-AT-normalesup.org> wxPython IPython GUI,
+  frontend architecture.
 
-* [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu>: maintainer of the
-  PyReadline project, necessary for IPython under windows.
+* **Barry Wark** <barrywark-AT-gmail.com> Cocoa GUI, frontend architecture.
 
+* **Laurent Dufrechou** <laurent.dufrechou-AT-gmail.com> wxPython IPython GUI.
+
+* **Jörgen Stenarson** <jorgen.stenarson-AT-bostream.nu> Maintainer of the
+  PyReadline project, which is needed for IPython under windows.
+
+Special thanks
+==============
 
 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).
+Bill Bumgarner <bbum-AT-friday.com>, for providing the DPyGetOpt module that
+IPython used for parsing command line options through version 0.10.
 
-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.
+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).
+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.
 
-Obviously Guido van Rossum and the whole Python development team, that
-goes without saying.
+Obviously Guido van Rossum and the whole Python development team, for creating
+a great language for interactive computing.
 
-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.
+Enthought (http://www.enthought.com), for hosting IPython's website and
+supporting the project in various ways over the years.
 
 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:
+an O'Reilly Python editor. His October 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 us
-know if we have ommitted your name by accident:
+Contributors
+============
+
+And last but not least, all the kind IPython contributors who have contributed
+new code, bug reports, fixes, comments and ideas. A brief list follows, please
+let us know if we have omitted your name by accident:
 
-* Dan Milstein <danmil-AT-comcast.net>.  A bold refactoring of the 
-  core prefilter stuff in the IPython interpreter.
+* Dan Milstein <danmil-AT-comcast.net> A bold refactor of the core prefilter
+  machinery in the IPython interpreter.
 
-* [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
-  color problem. This bug alone caused many lost hours and
-  frustration, many thanks to him for the fix. I've always been a
-  fan of Ogg & friends, now I have one more reason to like these folks.
-  Jack is also contributing with Debian packaging and many other
-  things.
+* 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.
+* 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.
+* 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.
+* 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.
+* 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.
+* Dryice Liu <dryice-AT-liu.com.cn> FreeBSD port.
 
-* [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
+* Mike Heeter <korora-AT-SDF.LONESTAR.ORG>
 
-* [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
+* Christopher Hart <hart-AT-caltech.edu> PDB integration.
 
-* [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
+* Milan Zamazal <pdm-AT-zamazal.org> Emacs info.
 
-* [Philip Hisley] <compsys-AT-starpower.net>
+* Philip Hisley <compsys-AT-starpower.net>
 
-* [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
-  more.
+* Holger Krekel <pyth-AT-devel.trillke.net> Tab completion, lots more.
 
-* [Robin Siebler] <robinsiebler-AT-starband.net>
+* Robin Siebler <robinsiebler-AT-starband.net>
 
-* [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
+* Ralf Ahlbrink <ralf_ahlbrink-AT-web.de>
 
-* [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
+* Thorsten Kampe <thorsten-AT-thorstenkampe.de>
 
-* [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
+* Fredrik Kant <fredrik.kant-AT-front.com> Windows setup.
 
-* [Syver Enstad] <syver-en-AT-online.no> Windows setup.
+* Syver Enstad <syver-en-AT-online.no> Windows setup.
 
-* [Richard] <rxe-AT-renre-europe.com> Global embedding.
+* Richard <rxe-AT-renre-europe.com> Global embedding.
 
-* [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
+* Hayden Callow <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
   compatibility.
   
-* [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
+* Leonardo Santagada <retype-AT-terra.com.br> Fixes for Windows
   installation.
   
-* [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
+* Christopher Armstrong <radix-AT-twistedmatrix.com> Bugfixes.
 
-* [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
+* Francois Pinard <pinard-AT-iro.umontreal.ca> Code and
   documentation fixes.
   
-* [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
+* 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.
+* Olivier Aubert <oaubert-AT-bat710.univ-lyon1.fr> New magics.
 
-* [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
+* King C. Shu <kingshu-AT-myrealbox.com> Autoindent patch.
 
-* [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
+* Chris Drexler <chris-AT-ac-drexler.de> Readline packages for
   Win32/CygWin.
   
-* [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
+* Gustavo Cordova Avila <gcordova-AT-sismex.com> EvalDict code for
   nice, lightweight string interpolation.
   
-* [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
+* Kasper Souren <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
 
-* [Gever Tulley] <gever-AT-helium.com> Code contributions.
+* Gever Tulley <gever-AT-helium.com> Code contributions.
 
-* [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
+* Ralf Schmitt <ralf-AT-brainbot.com> Bug reports & fixes.
 
-* [Oliver Sander] <osander-AT-gmx.de> Bug reports.
+* Oliver Sander <osander-AT-gmx.de> Bug reports.
 
-* [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
+* Rod Holland <rhh-AT-structurelabs.com> Bug reports and fixes to
   logging module.
 
-* [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
+* 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
+* 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
+* 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
+* 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
+* Antoon Pardon <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
   the multithreaded IPython.
 
-* [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
+* 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.
+* Matthew Arnison <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
 
-* [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
+* 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
+* Norbert Tretkowski <tretkowski-AT-inittab.de> help with Debian
   packaging and distribution.
 
-* [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
+* 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
+* Jörgen Stenarson <jorgen.stenarson-AT-bostream.nu> Wildcard
   support implementation for searching namespaces.
 
-* [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
+* 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
+* 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
+* Alexander Belchenko <bialix-AT-ukr.net> Improvements for win32
   paging system.
 
-* [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
+* Will Maier <willmaier-AT-ml1.net> Official OpenBSD port.
 
-* [Ondrej Certik] <ondrej-AT-certik.cz>: set up the IPython docs to use the new
+* Ondrej Certik <ondrej-AT-certik.cz> Set up the IPython docs to use the new
   Sphinx system used by Python, Matplotlib and many more projects.
 
-* [Stefan van der Walt] <stefan-AT-sun.ac.za>: support for the new config system.
+* Stefan van der Walt <stefan-AT-sun.ac.za> Design and prototype of the
+  Traits based config system.
 

docs/source/about/history.txt

@@ -1,38 +1,34 b''
 .. _history:
 
 =======
 History
 =======
 
 Origins
 =======
 
-IPython was starting in 2001 by Fernando Perez.  IPython as we know it
-today grew out of the following three projects:
-
-* ipython by Fernando Pérez. I was working on adding
-  Mathematica-type prompts and a flexible configuration system
-  (something better than $PYTHONSTARTUP) to the standard Python
-  interactive interpreter.
+IPython was starting in 2001 by Fernando Perez while he was a graduate student
+at the University of Colorado, Boulder. IPython as we know it today grew out
+of the following three projects:
+
+* ipython by Fernando Pérez. Fernando began using Python and ipython began as
+  an outgrowth of his desire for things like Mathematica-style prompts, access
+  to previous output (again like Mathematica's % syntax) and a flexible
+  configuration system (something better than :envvar:`PYTHONSTARTUP`).
 * 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.
+  an old help system. IPP was used as the "container" code into
+  which Fernando added the functionality from ipython and LazyPython.
 * LazyPython by Nathan Gray. Simple but very powerful. The quick
   syntax (auto parens, auto quotes) and verbose/colored tracebacks
   were all taken from here.
 
-Here is how Fernando describes it:
+Here is how Fernando describes the early history of IPython:
 
     When I found out about IPP and LazyPython I tried to join all three
     into a unified system. I thought this could provide a very nice
     working environment, both for regular programming and scientific
     computing: shell-like features, IDL/Matlab numerics, Mathematica-type
     prompt history and great object introspection and help facilities. I
     think it worked reasonably well, though it was a lot more work than I
     had initially planned.
 
-Today and how we got here
-=========================
-
-This needs to be filled in.
-

docs/source/about/license_and_copyright.txt

@@ -1,92 +1,95 b''
 .. _license:
 
 =====================
 License and Copyright
 =====================
 
 License
 =======
 
-IPython is licensed under the terms of the new or revised BSD license, as follows::
+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
+<jhauser-AT-zscout.de> and Nathaniel Gray <n8gray-AT-caltech.edu>. 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
+* 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
+* 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.
+contributions are typically only changes (diffs/commits) 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.
+
+Any new code contributed to IPython must be licensed under the BSD license or
+a similar (MIT) open source license.
 
 Miscellaneous
 =============
 
 Some files (DPyGetOpt.py, for example) may be licensed under different
 conditions. Ultimately each file indicates clearly the conditions under which
 its author/authors have decided to publish the code.
 
 Versions of IPython up to and including 0.6.3 were released under the GNU
 Lesser General Public License (LGPL), available at
 http://www.gnu.org/copyleft/lesser.html.
 

docs/source/development/coding_guide.txt

@@ -1,142 +1,156 b''
 ==============
  Coding guide
 ==============
 
 
 Coding conventions
 ==================
 
 In general, we'll try to follow the standard Python style conventions as
 described in Python's `PEP 8`_, the official Python Style Guide.
 
 .. _PEP 8: 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, *never* use hard tabs.
 
 - 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 of PEP 8.  Some of
 the existing code doesn't honor this perfectly, but 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 some of the existing 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.
 
+Older material
+==============
 
-.. _devel-testing:
+General
+-------
 
-Testing system
-==============
+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 an interface.
+
+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.
+
+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.
 
-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/doc_guide.txt

@@ -1,104 +1,141 b''
 .. _documenting-ipython:
 
 =====================
  Documenting IPython
 =====================
 
 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.
 
 The actual HTML and PDF docs are built using the Sphinx_ documentation
 generation tool.  Sphinx has been adopted as the default documentation tool for
 Python itself as of version 2.6, as well as by a number of projects that
 IPython is related with, such as numpy, scipy, matplotlib, sage and nipy.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx.pocoo.org/
 
 
 The rest of this document is mostly taken from the `matploblib
 documentation`__; we are using a number of Sphinx tools and extensions written
 by the matplotlib team and will mostly follow their conventions, which are
 nicely spelled out in their guide.  What follows is thus a lightly adapted
 version of the matplotlib documentation guide, taken with permission from the
 MPL team.
 
 .. __: http://matplotlib.sourceforge.net/devel/documenting_mpl.html
 
 
 A bit of Python code::
 
     for i in range(10):
         print i,
     print "A big number:",2**34
 
 An interactive Python session::
 
     >>> from IPython import genutils
     >>> genutils.get_ipython_dir()
     '/home/fperez/.ipython'
 
 
 An IPython session:
 
 .. code-block:: ipython
 
   In [7]: import IPython
 
   In [8]: print "This IPython is version:",IPython.__version__
   This IPython is version: 0.9.1
 
   In [9]: 2+4
   Out[9]: 6
 
 
 A bit of shell code:
 
 .. code-block:: bash
 
     cd /tmp
     echo "My home directory is: $HOME"
     ls
 
   
 Docstring format
 ================
 
 Good docstrings are very important.  Unfortunately, Python itself only provides
 a rather loose standard for docstrings (`PEP 257`_), and there is no universally
 accepted convention for all the different parts of a complete docstring.
 However, the NumPy project has established a very reasonable standard, and has
 developed some tools to support the smooth inclusion of such docstrings in
 Sphinx-generated manuals.  Rather than inventing yet another pseudo-standard,
 IPython will be henceforth documented using the NumPy conventions; we carry
 copies of some of the NumPy support tools to remain self-contained, but share
 back upstream with NumPy any improvements or fixes we may make to the tools.
 
 The `NumPy documentation guidelines`_ contain detailed information on this
 standard, and for a quick overview, the NumPy `example docstring`_ is a useful
 read. 
 
 As in the past IPython used epydoc, currently many docstrings still use epydoc
 conventions.  We will update them as we go, but all new code should be fully
 documented using the NumPy standard.
 
 .. _PEP 257: http://www.python.org/peps/pep-0257.html
 .. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
 
 .. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt
 
 Additional PEPs of interest regarding documentation of code.  While both of
 these were rejected, the ideas therein form much of the basis of docutils (the
 machinery to process reStructuredText):
 
 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
 
+Older material
+==============
+
+Documentation
+=============
+
+Standalone documentation
+------------------------
+
+All standalone documentation should be written in plain text (``.txt``) files
+using reStructuredText [reStructuredText]_ for markup and formatting. All such
+documentation should be placed in directory :file:`docs/source` of the IPython
+source tree. The documentation in this location will serve as the main source
+for IPython documentation and all existing documentation should be converted
+to this format.
+
+To build the final documentation, we use Sphinx [Sphinx]_.  Once you have
+Sphinx installed, you can build the html docs yourself by doing::
+
+    $ cd ipython-mybranch/docs
+    $ make html
+
+Docstring format
+----------------
+
+Good docstrings are very important. All new code should have docstrings that
+are formatted using reStructuredText for markup and formatting, since it is
+understood by a wide variety of tools. Details about using reStructuredText
+for docstrings can be found `here
+<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+
+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>`_
+

docs/source/development/index.txt

@@ -1,16 +1,25 b''
-===========================
- IPython Developer's Guide
-===========================
+.. _developer_guide:
+
+=========================
+IPython developer's guide
+=========================
 
 .. toctree::
    :maxdepth: 2
 
-   overview.txt
+   contributing.txt
    coding_guide.txt
    doc_guide.txt
+   testing.txt
+   release.txt
    roadmap.txt
 
    notification_blueprint.txt
-   config_blueprint.txt
    reorg.txt
 
+
+.. [Bazaar] Bazaar. http://bazaar-vcs.org/
+.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
+.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
+.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
+.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
  No newline at end of file

docs/source/development/notification_blueprint.txt

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

docs/source/development/overview.txt

@@ -1,518 +1,8 b''
-.. _development:
 
-==============================
-IPython development guidelines
-==============================
 
 
-Overview
-========
 
-This document describes IPython from the perspective of developers. Most
-importantly, it gives information for people who want to contribute to the
-development of IPython. So if you want to help out, read on!
 
-How to contribute to IPython
-============================
 
-IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
-This makes it easy for people to contribute to the development of IPython.
-There are several ways in which you can join in.
 
-If you have a small change that you want to send to the team, you can edit your
-bazaar checkout of IPython (see below) in-place, and ask bazaar for the
-differences::
-
-    $ cd /path/to/your/copy/of/ipython
-    $ bzr diff > my_fixes.diff
-
-This produces a patch file with your fixes, which we can apply to the source
-tree.  This file should then be attached to a ticket in our `bug tracker
-<https://bugs.launchpad.net/ipython>`_, indicating what it does.
-
-This model of creating small, self-contained patches works very well and there
-are open source projects that do their entire development this way.  However,
-in IPython we have found that for tracking larger changes, making use of
-bazaar's full capabilities in conjunction with Launchpad's code hosting
-services makes for a much better experience.
-
-Making your own branch of IPython allows you to refine your changes over time,
-track the development of the main team, and propose your own full version of
-the code for others to use and review, with a minimum amount of fuss.  The next
-parts of this document will explain how to do this.
-
-Install Bazaar and create a Launchpad account
----------------------------------------------
-
-First make sure you have installed Bazaar (see their `website
-<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
-you, try the following::
-
-    $ bzr whoami
-    Joe Coder <[e-mail]>
-
-This should display your name and email. Next, you will want to create an
-account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
-ssh keys. For more information of setting up your ssh keys, see `this link
-<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
-
-Get the main IPython branch from Launchpad
-------------------------------------------
-
-Now, you can get a copy of the main IPython development branch (we call this
-the "trunk")::
-
-    $ bzr branch lp:ipython
-
-Create a working branch
------------------------
-
-When working on IPython, you won't actually make edits directly to the
-:file:`lp:ipython` branch. Instead, you will create a separate branch for your
-changes. For now, let's assume you want to do your work in a branch named
-"ipython-mybranch". Create this branch by doing::
-
-    $ bzr branch ipython ipython-mybranch
-
-When you actually create a branch, you will want to give it a name that
-reflects the nature of the work that you will be doing in it, like
-"install-docs-update".
-
-Make edits in your working branch
----------------------------------
-
-Now you are ready to actually make edits in your :file:`ipython-mybranch`
-branch. Before doing this, it is helpful to install this branch so you can
-test your changes as you work. This is easiest if you have setuptools
-installed. Then, just do::
-
-    $ cd ipython-mybranch
-    $ python setupegg.py develop
-
-Now, make some changes. After a while, you will want to commit your changes.
-This let's Bazaar know that you like the changes you have made and gives you
-an opportunity to keep a nice record of what you have done. This looks like
-this::
-
-    $ ...do work in ipython-mybranch...
-    $ bzr commit -m "the commit message goes here"
-
-Please note that since we now don't use an old-style linear ChangeLog (that
-tends to cause problems with distributed version control systems), you should
-ensure that your log messages are reasonably detailed.  Use a docstring-like
-approach in the commit messages (including the second line being left
-*blank*)::
-
-  Single line summary of  changes being committed.
-
-  * more details when warranted ...
-  * including crediting outside contributors if they sent the
-    code/bug/idea!
-
-As you work, you will repeat this edit/commit cycle many times. If you work on
-your branch for a long time, you will also want to get the latest changes from
-the :file:`lp:ipython` branch. This can be done with the following sequence of
-commands::
-
-    $ ls
-    ipython
-    ipython-mybranch
-    
-    $ cd ipython
-    $ bzr pull
-    $ cd ../ipython-mybranch
-    $ bzr merge ../ipython
-    $ bzr commit -m "Merging changes from trunk"
-
-Along the way, you should also run the IPython test suite.  You can do this
-using the :command:`iptest` command (which is basically a customized version of
-:command:`nosetests`)::
-
-    $ cd
-    $ iptest
-
-The :command:`iptest` command will also pick up and run any tests you have
-written. See :ref:`testing documentation <devel_testing>` for further details
-on the testing system.
-
-
-Post your branch and request a code review
-------------------------------------------
-
-Once you are done with your edits, you should post your branch on Launchpad so
-that other IPython developers can review the changes and help you merge your
-changes into the main development branch. To post your branch on Launchpad,
-do::
-
-    $ cd ipython-mybranch
-    $ bzr push lp:~yourusername/ipython/ipython-mybranch
-
-Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
-should see your branch under the "Code" tab. If you click on your branch, you
-can provide a short description of the branch as well as mark its status. Most
-importantly, you should click the link that reads "Propose for merging into
-another branch". What does this do?
-
-This let's the other IPython developers know that your branch is ready to be
-reviewed and merged into the main development branch. During this review
-process, other developers will give you feedback and help you get your code
-ready to be merged. What types of things will we be looking for:
-
-* All code is documented.
-* All code has tests.
-* The entire IPython test suite passes.
-
-Once your changes have been reviewed and approved, someone will merge them
-into the main development branch.
-
-
-Some notes for core developers when merging third-party contributions
-=====================================================================
-
-Core developers, who ultimately merge any approved branch (from themselves,
-another developer, or any third-party contribution) will typically use
-:command:`bzr merge` to merge the branch into the trunk and push it to the
-main Launcphad site. This is a short list of things to keep in mind when doing
-this process, so that the project history is easy to understand in the long
-run, and that generating release notes is as painless and accurate as
-possible.
-
-- When you merge any non-trivial functionality (from one small bug fix to a
-  big feature branch), please remember to always edit the :file:`changes.txt`
-  file accordingly. This file has one main section for each release, and if
-  you edit it as you go, noting what new features, bug fixes or API changes
-  you have made, the release notes will be almost finished when they are
-  needed later. This is much easier if done when you merge the work, rather
-  than weeks or months later by re-reading a massive Bazaar log.
-
-- When big merges are done, the practice of putting a summary commit message
-  in the merge is *extremely* useful. It makes this kind of job much nicer,
-  because that summary log message can be almost copy/pasted without changes,
-  if it was well written, rather than dissecting the next-level messages from
-  the individual commits.
-
-- It's important that we remember to always credit who gave us something if
-  it's not the committer. In general, we have been fairly good on this front,
-  this is just a reminder to keep things up. As a note, if you are ever
-  committing something that is completely (or almost so) a third-party
-  contribution, do the commit as::
-
-    $ bzr commit --author="Someone Else"
-
-  This way it will show that name separately in the log, which makes it even
-  easier to spot. Obviously we often rework third party contributions
-  extensively, but this is still good to keep in mind for cases when we don't
-  touch the code too much.
-
-
-Documentation
-=============
-
-Standalone documentation
-------------------------
-
-All standalone documentation should be written in plain text (``.txt``) files
-using reStructuredText [reStructuredText]_ for markup and formatting. All such
-documentation should be placed in directory :file:`docs/source` of the IPython
-source tree. The documentation in this location will serve as the main source
-for IPython documentation and all existing documentation should be converted
-to this format.
-
-To build the final documentation, we use Sphinx [Sphinx]_.  Once you have
-Sphinx installed, you can build the html docs yourself by doing::
-
-    $ cd ipython-mybranch/docs
-    $ make html
-
-Docstring format
-----------------
-
-Good docstrings are very important. All new code should have docstrings that
-are formatted using reStructuredText for markup and formatting, since it is
-understood by a wide variety of tools. Details about using reStructuredText
-for docstrings can be found `here
-<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
-
-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 an interface.
-
-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.
-
-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
-[Nose]_ testing package will find. Regardless of how the tests are written, we
-will use Nose for discovering and running the tests. Nose will be required to
-run the IPython test suite, but will not be required to simply use IPython.
-
-Tests of Twisted using code need to follow two additional guidelines:
-
-1. Twisted using tests should be written by subclassing the :class:`TestCase`
-   class that comes with :mod:`twisted.trial.unittest`. 
-
-2. All :class:`Deferred` instances that are created in the test must be
-   properly chained and the final one *must* be the return value of the test
-   method.
-
-When these two things are done, Nose will be able to run the tests and the
-twisted reactor will be handled correctly.
-
-Each subpackage in IPython should have its own :file:`tests` directory that
-contains all of the tests for that subpackage. This allows each subpackage to
-be self-contained.  A good convention to follow is to have a file named
-:file:`test_foo.py` for each module :file:`foo.py` in the package.  This makes
-it easy to organize the tests, though like most conventions, it's OK to break
-it if logic and common sense dictate otherwise.
-
-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 ship a set of decorators in the
-:mod:`IPython.testing` package to tag tests that may be platform-specific or
-otherwise may have restrictions; if the existing ones don't fit your needs, add
-a new decorator in that location so other tests can reuse it.
-
-To run the IPython test suite, use the :command:`iptest` command that is
-installed with IPython (if you are using IPython in-place, without installing
-it, you can find this script in the :file:`scripts` directory)::
-
-    $ iptest
-
-This command colects all IPython tests into separate groups, and then calls
-either Nose with the proper options and extensions, or Twisted's
-:command:`trial`.  This ensures that tests that need the Twisted reactor
-management facilities execute separate of Nose.  If any individual test group
-fails, :command:`iptest` will print what you need to type so you can rerun that
-particular test group alone for debugging.
-
-By default, :command:`iptest` runs the entire IPython test
-suite (skipping tests that may be platform-specific or which depend on tools
-you may not have).  But you can also use it to run only one specific test file,
-or a specific test function.  For example, this will run only the
-:file:`test_magic` file from the test suite::
-
-    $ iptest IPython.tests.test_magic
-    ----------------------------------------------------------------------
-    Ran 10 tests in 0.348s
-
-    OK (SKIP=3)
-    Deleting object: second_pass
-
-while the ``path:function`` syntax allows you to select a specific function in
-that file to run::
-
-    $ iptest IPython.tests.test_magic:test_obj_del
-    ----------------------------------------------------------------------
-    Ran 1 test in 0.204s
-
-    OK
-
-Since :command:`iptest` is based on nosetests, you can pass it any regular
-nosetests option.  For example, you can use ``--pdb`` or ``--pdb-failures`` to
-automatically activate the interactive Pdb debugger on errors or failures.  See
-the nosetests documentation for further details.
-
-
-A few tips for writing tests
-----------------------------
-
-You can write tests either as normal test files, using all the conventions that
-Nose recognizes, or as doctests.  Note that *all* IPython functions should have
-at least one example that serves as a doctest, whenever technically feasible.
-However, example doctests should only be in the main docstring if they are *a
-good example*, i.e. if they convey useful information about the function.  If
-you simply would like to write a test as a doctest, put it in a separate test
-file and write a no-op function whose only purpose is its docstring.
-
-Note, however, that in a file named :file:`test_X`, functions whose only test
-is their docstring (as a doctest) and which have no test functionality of their
-own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
-double-counted (the empty function call is counted as a test, which just
-inflates tests numbers artificially).  This restriction does not apply to
-functions in files with other names, due to how Nose discovers tests.
-
-You can use IPython examples in your docstrings.  Those can make full use of
-IPython functionality (magics, variable substitution, etc), but be careful to
-keep them generic enough that they run identically on all Operating Systems.
-
-The prompts in your doctests can be either of the plain Python ``>>>`` variety
-or ``In [1]:`` IPython style.  Since this is the IPython system, after all, we
-encourage you to use IPython prompts throughout, unless you are illustrating a
-specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
-
-If a test isn't safe to run inside the main nose process (e.g. because it loads
-a GUI toolkit), consider running it in a subprocess and capturing its output
-for evaluation and test decision later.  Here is an example of how to do it, by
-relying on the builtin ``_ip`` object that contains the public IPython api as
-defined in :mod:`IPython.ipapi`::
-
-   def test_obj_del():
-       """Test that object's __del__ methods are called on exit."""
-       test_dir = os.path.dirname(__file__)
-       del_file = os.path.join(test_dir,'obj_del.py')
-       out = _ip.IP.getoutput('ipython %s' % del_file)
-       nt.assert_equals(out,'object A deleted')
-
-
-
-If a doctest contains input whose output you don't want to verify identically
-via doctest (random output, an object id, etc), you can mark a docstring with
-``#random``.  All of these test will have their code executed but no output
-checking will be done::
-
-       >>> 1+3
-       junk goes here...  # random
-
-       >>> 1+2
-       again,  anything goes #random
-       if multiline, the random mark is only needed once.
-
-       >>> 1+2
-       You can also put the random marker at the end:
-       # random
-
-       >>> 1+2
-       # random
-       .. or at the beginning.
-
-In a case where you want an *entire* docstring to be executed but not verified
-(this only serves to check that the code runs without crashing, so it should be
-used very sparingly), you can put ``# all-random`` in the docstring.
-       
-.. _devel_config:
-
-Release checklist
-=================
-
-Most of the release process is automated by the :file:`release` script in the
-:file:`tools` directory.  This is just a handy reminder for the release manager.
-
-#. First, run :file:`build_release`, which does all the file checking and
-   building that the real release script will do.  This will let you do test
-   installations, check that the build procedure runs OK, etc.  You may want to
-   disable a few things like multi-version RPM building while testing, because
-   otherwise the build takes really long.
-
-#. Run the release script, which makes the tar.gz, eggs and Win32 .exe
-   installer.  It posts them to the site and registers the release with PyPI.
-
-#. Updating the website with announcements and links to the updated
-   changes.txt in html form. Remember to put a short note both on the news
-   page of the site and on Launcphad.
-
-#. Drafting a short release announcement with i) highlights and ii) a link to
-   the html changes.txt.
-
-#. Make sure that the released version of the docs is live on the site.
-
-#. Celebrate!
-
-Porting to 3.0
-==============
-
-There are no definite plans for porting of IPython to python 3. The major 
-issue is the dependency on twisted framework for the networking/threading 
-stuff. It is possible that it the traditional IPython interactive console 
-could be ported more easily since it has no such dependency. Here are a few
-things that will need to be considered when doing such a port especially
-if we want to have a codebase that works directly on both 2.x and 3.x.
-
-	1. The syntax for exceptions changed (PEP 3110). The old 
-	   `except exc, var` changed to `except exc as var`. At last
-	   count there was 78 occurences of this usage in the codebase.  This
-	   is  a particularly problematic issue, because it's not easy to
-	   implement it in a 2.5-compatible way.
-
-Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
-will likely at some point put out a release that requires strictly 2.6 and
-abandons 2.5 compatibility.  This will then allow us to port the code to using
-:func:`print` as a function, `except exc as var` syntax, etc.  But as of
-version 0.11 at least, we will retain Python 2.5 compatibility.
-
-
-.. [Bazaar] Bazaar. http://bazaar-vcs.org/
-.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
-.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
-.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
-.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
 

docs/source/development/roadmap.txt

@@ -1,94 +1,114 b''
 .. _roadmap:
 
 ===================
 Development roadmap
 ===================
 
 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.
 
 Work targeted to particular releases
 ====================================
 
 Release 0.11
 ------------
 
 * Full module and package reorganization (done).
 
 * Removal of the threaded shells and new implementation of GUI support
   based on ``PyOSInputHook`` (done).
 
 * Refactor the configuration system (done).
 
 * Prepare to refactor IPython's core by creating a new component and 
   application system (done).
 
 * Start to refactor IPython's core by turning everything into components
   (started).
 
 Release 0.12
 ------------
 
 * Continue to refactor IPython's core by turning everything into components.
 
 
 Major areas of work
 ===================
 
 Refactoring the main IPython core
 ---------------------------------
 
 During the summer of 2009, we began refactoring IPython's core.  The main
 thrust in this work was make the IPython core into a set of loosely coupled
 components.  The base component class for this is 
 :class:`IPython.core.component.Component`.  This section outlines the status
 of this work.
 
 Parts of the IPython core that have been turned into components:
 
 * The main :class:`InteractiveShell` class.
 * The aliases (:mod:`IPython.core.aliases`).
 * The display and builtin traps (:mod:`IPython.core.display_trap` and
   :mod:`IPython.core.builtin_trap`).
 * The prefilter machinery (:mod:`IPython.core.prefilter`).
 
 Parts of the IPythoncore that need to be turned into components:
 
 * Magics.
 * Input and output history management.
 * Prompts.
 * Completers.
 * Logging.
 * Exception handling.
 * Anything else.
 
 Process management for :mod:`IPython.kernel`
 --------------------------------------------
 
 Performance problems
 --------------------
 
 Currently, we have a number of performance issues in :mod:`IPython.kernel`:
 
 * The controller stores a large amount of state in Python dictionaries. Under
   heavy usage, these dicts with get very large, causing memory usage problems.
   We need to develop more scalable solutions to this problem. This will also
   help the controller to be more fault tolerant.
 
 * 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. The best approach for this is to
   separate the controller itself into multiple processes, one for the core
   controller and one each for the controller interfaces.
 
+Porting to 3.0
+==============
+
+There are no definite plans for porting of IPython to Python 3. The major 
+issue is the dependency on Twisted framework for the networking/threading 
+stuff. It is possible that it the traditional IPython interactive console 
+could be ported more easily since it has no such dependency. Here are a few
+things that will need to be considered when doing such a port especially
+if we want to have a codebase that works directly on both 2.x and 3.x.
+
+1. The syntax for exceptions changed (PEP 3110). The old `except exc, var`
+changed to `except exc as var`. At last count there was 78 occurrences of this
+usage in the code base. This is a particularly problematic issue, because it's
+not easy to implement it in a 2.5-compatible way.
+
+Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
+will likely at some point put out a release that requires strictly 2.6 and
+abandons 2.5 compatibility.  This will then allow us to port the code to using
+:func:`print` as a function, `except exc as var` syntax, etc.  But as of
+version 0.11 at least, we will retain Python 2.5 compatibility.

docs/source/faq.txt

@@ -1,96 +1,93 b''
 .. _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 :class:`MultiEngineClient`.
 
 What is the best way to use MPI from Python?
 --------------------------------------------
 
 What about all the other parallel computing packages in Python?
 ---------------------------------------------------------------
 
 Some of the unique characteristic of IPython are:
 
 * IPython is the only architecture that abstracts out the notion of a 
   parallel computation in such a way that new models of parallel computing
   can be explored quickly and easily.  If you don't like the models we
   provide, you can simply create your own using the capabilities we provide.
   
 * IPython is asynchronous from the ground up (we use `Twisted`_).
 
 * IPython's architecture is designed to avoid subtle problems 
   that emerge because of Python's global interpreter lock (GIL).
   
 * While IPython's architecture is designed to support a wide range
   of novel parallel computing models, it is fully interoperable with
   traditional MPI applications.
   
 * IPython has been used and tested extensively on modern supercomputers.
 
 * IPython's networking layers are completely modular.  Thus, is 
   straightforward to replace our existing network protocols with 
   high performance alternatives (ones based upon Myranet/Infiniband).
   
 * IPython is designed from the ground up to support collaborative
   parallel computing.  This enables multiple users to actively develop
   and run the *same* parallel computation.
   
 * Interactivity is a central goal for us.  While IPython does not have
   to be used interactivly, it can be.
       
 .. _Twisted: http://www.twistedmatrix.com
 
 Why The IPython controller a bottleneck in my parallel calculation?
 -------------------------------------------------------------------
 
 A golden rule in parallel computing is that you should only move data around if you
 absolutely need to. The main reason that the controller becomes a bottleneck is that
 too much data is being pushed and pulled to and from the engines. If your algorithm
 is structured in this way, you really should think about alternative ways of
 handling the data movement. Here are some ideas:
 
 1. Have the engines write data to files on the locals disks of the engines.
 
 2. Have the engines write data to files on a file system that is shared by
    the engines.
 
 3. Have the engines write data to a database that is shared by the engines.
 
 4. Simply keep data in the persistent memory of the engines and move the
    computation to the data (rather than the data to the computation).
 
 5. See if you can pass data directly between engines using MPI.
 
-Isn't Python slow to be used for high-performance parallel computing?
----------------------------------------------------------------------
-

docs/source/index.txt

@@ -1,34 +1,33 b''
 =====================
 IPython Documentation
 =====================
 
 .. htmlonly::
 
    :Release: |release|
    :Date: |today|
 
-Welcome to the official IPython documentation.  This document describes the
-various parts of IPython that are relevant to both users and developers.
+Welcome to the official IPython documentation.
 
 Contents
 ========
 
 .. toctree::
    :maxdepth: 1
 
    overview.txt
    whatsnew/index.txt
    install/index.txt
    interactive/index.txt
    parallel/index.txt
    config/index.txt
    development/index.txt
    api/index.txt
    faq.txt
    about/index.txt
 
 .. htmlonly::
    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`
 

docs/source/install/install.txt

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

docs/source/interactive/index.txt

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

docs/source/interactive/reference.txt

@@ -1,1569 +1,1577 b''
 =================
 IPython reference
 =================
 
+.. warning::
+
+    As of the 0.11 version of IPython, some of the features and APIs
+    described in this section have been deprecated or are broken.  Our plan
+    is to continue to support these features, but they need to be updated
+    to take advantage of recent API changes.  Furthermore, this section
+    of the documentation need to be updated to reflect all of these changes.
+
 .. _command_line_options:
 
 Command-line usage
 ==================
 
 You start IPython with the command::
 
     $ ipython [options] files
 
 If invoked with no options, it executes all the files listed in sequence
 and drops you into the interpreter while still acknowledging any options
 you may have set in your ipythonrc file. This behavior is different from
 standard Python, which when called as python -i will only execute one
 file and ignore your configuration setup.
 
 Please note that some of the configuration options are not available at
 the command line, simply because they are not practical here. Look into
 your ipythonrc configuration file for details on those. This file
 typically installed in the $HOME/.ipython directory. For Windows users,
 $HOME resolves to C:\\Documents and Settings\\YourUserName in most
 instances. In the rest of this text, we will refer to this directory as
 IPYTHONDIR.
 
 
 
 Special Threading Options
 -------------------------
 
 Previously IPython had command line options for controlling GUI event loop
 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
 version 0.11, these have been deprecated. Please see the new ``%gui``
 magic command or :ref:`this section <gui_support>` for details on the new
 interface.
 
 Regular Options
 ---------------
 
 After the above threading options have been given, regular options can
 follow in any order. All options can be abbreviated to their shortest
 non-ambiguous form and are case-sensitive. One or two dashes can be
 used. Some options have an alternate short form, indicated after a ``|``.
 
 Most options can also be set from your ipythonrc configuration file. See
 the provided example for more details on what the options do. Options
 given at the command line override the values set in the ipythonrc file.
 
 All options with a [no] prepended can be specified in negated form
 (-nooption instead of -option) to turn the feature off.
 
     -help  print a help message and exit.
 
     -pylab
     Deprecated.  See :ref:`Matplotlib support <matplotlib_support>`
     for more details.
 
     -autocall <val>
 	Make IPython automatically call any callable object even if you
 	didn't type explicit parentheses. For example, 'str 43' becomes
 	'str(43)' automatically. The value can be '0' to disable the feature,
 	'1' for smart autocall, where it is not applied if there are no more
 	arguments on the line, and '2' for full autocall, where all callable
 	objects are automatically called (even if no arguments are
 	present). The default is '1'.
 
     -[no]autoindent    
 	Turn automatic indentation on/off.
 
     -[no]automagic 
 	make magic commands automatic (without needing their first character
 	to be %). Type %magic at the IPython prompt for more information.
 
     -[no]autoedit_syntax 
 	When a syntax error occurs after editing a file, automatically
 	open the file to the trouble causing line for convenient
 	fixing.
 
     -[no]banner		Print the initial information banner (default on).
 
     -c <command>
 	execute the given command string. This is similar to the -c
 	option in the normal Python interpreter.
 
     -cache_size, cs <n> 
 	size of the output cache (maximum number of entries to hold in
 	memory). The default is 1000, you can change it permanently in your
 	config file. Setting it to 0 completely disables the caching system,
 	and the minimum value accepted is 20 (if you provide a value less than
 	20, it is reset to 0 and a warning is issued) This limit is defined
 	because otherwise you'll spend more time re-flushing a too small cache
 	than working.
 
     -classic, cl 
 	Gives IPython a similar feel to the classic Python
 	prompt.
 
     -colors <scheme> 
 	Color scheme for prompts and exception reporting. Currently
 	implemented: NoColor, Linux and LightBG.
 
     -[no]color_info 
 	IPython can display information about objects via a set of functions,
 	and optionally can use colors for this, syntax highlighting source
 	code and various other elements.  However, because this information is
 	passed through a pager (like 'less') and many pagers get confused with
 	color codes, this option is off by default. You can test it and turn
 	it on permanently in your ipythonrc file if it works for you. As a
 	reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
 	that in RedHat 7.2 doesn't.
 
 	Test it and turn it on permanently if it works with your
 	system. The magic function %color_info allows you to toggle this
 	interactively for testing.
 
     -[no]debug 
 	Show information about the loading process. Very useful to pin down
 	problems with your configuration files or to get details about
 	session restores.
 
     -[no]deep_reload: 
 	IPython can use the deep_reload module which reloads changes in
 	modules recursively (it replaces the reload() function, so you don't
 	need to change anything to use it).  deep_reload() forces a full
 	reload of modules whose code may have changed, which the default
 	reload() function does not.
 
 	When deep_reload is off, IPython will use the normal reload(),
 	but deep_reload will still be available as dreload(). This
 	feature is off by default [which means that you have both
 	normal reload() and dreload()].
 
     -editor <name>
 	Which editor to use with the %edit command. By default,
 	IPython will honor your EDITOR environment variable (if not
 	set, vi is the Unix default and notepad the Windows one).
 	Since this editor is invoked on the fly by IPython and is
 	meant for editing small code snippets, you may want to use a
 	small, lightweight editor here (in case your default EDITOR is
 	something like Emacs).
 
     -ipythondir <name> 
 	name of your IPython configuration directory IPYTHONDIR. This
 	can also be specified through the environment variable
 	IPYTHONDIR.
 
     -log, l 
 	generate a log file of all input. The file is named
 	ipython_log.py in your current directory (which prevents logs
 	from multiple IPython sessions from trampling each other). You
 	can use this to later restore a session by loading your
 	logfile as a file to be executed with option -logplay (see
 	below).
 
     -logfile, lf <name>   specify the name of your logfile.
 
     -logplay, lp <name> 
 
       you can replay a previous log. For restoring a session as close as
       possible to the state you left it in, use this option (don't just run
       the logfile). With -logplay, IPython will try to reconstruct the
       previous working environment in full, not just execute the commands in
       the logfile.
 
       When a session is restored, logging is automatically turned on
       again with the name of the logfile it was invoked with (it is
       read from the log header). So once you've turned logging on for
       a session, you can quit IPython and reload it as many times as
       you want and it will continue to log its history and restore
       from the beginning every time.
       
       Caveats: there are limitations in this option. The history
       variables _i*,_* and _dh don't get restored properly. In the
       future we will try to implement full session saving by writing
       and retrieving a 'snapshot' of the memory state of IPython. But
       our first attempts failed because of inherent limitations of
       Python's Pickle module, so this may have to wait.
 
     -[no]messages   
 	Print messages which IPython collects about its startup
 	process (default on).
 
     -[no]pdb
 	Automatically call the pdb debugger after every uncaught
 	exception. If you are used to debugging using pdb, this puts
 	you automatically inside of it after any call (either in
 	IPython or in code called by it) which triggers an exception
 	which goes uncaught.
 
     -pydb
 	Makes IPython use the third party "pydb" package as debugger,
 	instead of pdb. Requires that pydb is installed.
 	
     -[no]pprint
 	ipython can optionally use the pprint (pretty printer) module
 	for displaying results. pprint tends to give a nicer display
 	of nested data structures. If you like it, you can turn it on
 	permanently in your config file (default off).
 
     -profile, p <name>
 
 	assume that your config file is ipythonrc-<name> or
 	ipy_profile_<name>.py (looks in current dir first, then in
 	IPYTHONDIR).  This is a quick way to keep and load multiple
 	config files for different tasks, especially if you use the
 	include option of config files. You can keep a basic
 	IPYTHONDIR/ipythonrc file and then have other 'profiles' which
 	include this one and load extra things for particular
 	tasks. For example:
 
 	1. $HOME/.ipython/ipythonrc : load basic things you always want.
 	2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
 	3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
 
 	Since it is possible to create an endless loop by having
 	circular file inclusions, IPython will stop if it reaches 15
 	recursive inclusions.
 
     -prompt_in1, pi1 <string>
 
         Specify the string used for input prompts. Note that if you are using
 	numbered prompts, the number is represented with a '\#' in the
 	string. Don't forget to quote strings with spaces embedded in
 	them. Default: 'In [\#]:'.  The :ref:`prompts section <prompts>`
 	discusses in detail all the available escapes to customize your
 	prompts.
 
     -prompt_in2, pi2 <string>
 	Similar to the previous option, but used for the continuation
 	prompts. The special sequence '\D' is similar to '\#', but
 	with all digits replaced dots (so you can have your
 	continuation prompt aligned with your input prompt).  Default:
 	' .\D.:' (note three spaces at the start for alignment with
 	'In [\#]').
 
     -prompt_out,po <string> 
 	String used for output prompts, also uses numbers like
 	prompt_in1. Default: 'Out[\#]:'
 
     -quick   start in bare bones mode (no config file loaded).
 
     -rcfile <name>   
 	name of your IPython resource configuration file. Normally
 	IPython loads ipythonrc (from current directory) or
 	IPYTHONDIR/ipythonrc.
 
 	If the loading of your config file fails, IPython starts with
 	a bare bones configuration (no modules loaded at all).
 
     -[no]readline
 	use the readline library, which is needed to support name
 	completion and command history, among other things.  It is
 	enabled by default, but may cause problems for users of
 	X/Emacs in Python comint or shell buffers.
 
 	Note that X/Emacs 'eterm' buffers (opened with M-x term) support
 	IPython's readline and syntax coloring fine, only 'emacs' (M-x
 	shell and C-c !) buffers do not.
 
     -screen_length, sl <n>
 	number of lines of your screen. This is used to control
 	printing of very long strings. Strings longer than this number
 	of lines will be sent through a pager instead of directly
 	printed.
 
 	The default value for this is 0, which means IPython will
 	auto-detect your screen size every time it needs to print certain
 	potentially long strings (this doesn't change the behavior of the
 	'print' keyword, it's only triggered internally). If for some
 	reason this isn't working well (it needs curses support), specify
 	it yourself. Otherwise don't change the default.
 
     -separate_in, si <string>
 
 	separator before input prompts.
 	Default: '\n'
 
     -separate_out, so <string>  
         separator before output prompts.
         Default: nothing.
 
     -separate_out2, so2
 	separator after output prompts.
 	Default: nothing.
 	For these three options, use the value 0 to specify no separator.
 
     -nosep   
 	shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
 	0'. Simply removes all input/output separators.
 
     -upgrade 
 	allows you to upgrade your IPYTHONDIR configuration when you
 	install a new version of IPython. Since new versions may
 	include new command line options or example files, this copies
 	updated ipythonrc-type files. However, it backs up (with a
 	.old extension) all files which it overwrites so that you can
 	merge back any customizations you might have in your personal
 	files. Note that you should probably use %upgrade instead,
 	it's a safer alternative.
 
 
     -Version    print version information and exit.
 
     -wxversion <string> 
     Deprecated.
 
     -xmode <modename>
 
 	Mode for exception reporting.
 
 	Valid modes: Plain, Context and Verbose.
 
 	* Plain: similar to python's normal traceback printing.
 	* Context: prints 5 lines of context source code around each
 	  line in the traceback.
 	* Verbose: similar to Context, but additionally prints the
 	  variables currently visible where the exception happened
 	  (shortening their strings if too long). This can potentially be
 	  very slow, if you happen to have a huge data structure whose
 	  string representation is complex to compute. Your computer may
 	  appear to freeze for a while with cpu usage at 100%. If this
 	  occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
 	  more than once).
 
 Interactive use
 ===============
 
 Warning: IPython relies on the existence of a global variable called
 _ip which controls the shell itself. If you redefine _ip to anything,
 bizarre behavior will quickly occur.
 
 Other than the above warning, IPython is meant to work as a drop-in
 replacement for the standard interactive interpreter. As such, any code
 which is valid python should execute normally under IPython (cases where
 this is not true should be reported as bugs). It does, however, offer
 many features which are not available at a standard python prompt. What
 follows is a list of these.
 
 
 Caution for Windows users
 -------------------------
 
 Windows, unfortunately, uses the '\' character as a path
 separator. This is a terrible choice, because '\' also represents the
 escape character in most modern programming languages, including
 Python. For this reason, using '/' character is recommended if you
 have problems with ``\``.  However, in Windows commands '/' flags
 options, so you can not use it for the root directory. This means that
 paths beginning at the root must be typed in a contrived manner like:
 ``%copy \opt/foo/bar.txt \tmp``
 
 .. _magic:
 
 Magic command system
 --------------------
 
 IPython will treat any line whose first character is a % as a special
 call to a 'magic' function. These allow you to control the behavior of
 IPython itself, plus a lot of system-type features. They are all
 prefixed with a % character, but parameters are given without
 parentheses or quotes.
 
 Example: typing '%cd mydir' (without the quotes) changes you working
 directory to 'mydir', if it exists.
 
 If you have 'automagic' enabled (in your ipythonrc file, via the command
 line option -automagic or with the %automagic function), you don't need
 to type in the % explicitly. IPython will scan its internal list of
 magic functions and call one if it exists. With automagic on you can
 then just type 'cd mydir' to go to directory 'mydir'. The automagic
 system has the lowest possible precedence in name searches, so defining
 an identifier with the same name as an existing magic function will
 shadow it for automagic use. You can still access the shadowed magic
 function by explicitly using the % character at the beginning of the line.
 
 An example (with automagic on) should clarify all this::
 
     In [1]: cd ipython # %cd is called by automagic
 
     /home/fperez/ipython
 
     In [2]: cd=1 # now cd is just a variable
 
     In [3]: cd .. # and doesn't work as a function anymore
 
     ------------------------------
 
         File "<console>", line 1
 
           cd ..
 
               ^
 
     SyntaxError: invalid syntax
 
     In [4]: %cd .. # but %cd always works
 
     /home/fperez
 
     In [5]: del cd # if you remove the cd variable
 
     In [6]: cd ipython # automagic can work again
 
     /home/fperez/ipython
 
 You can define your own magic functions to extend the system. The
 following example defines a new magic command, %impall::
 
     import IPython.ipapi 
 
     ip = IPython.ipapi.get()
 
     def doimp(self, arg):
 
         ip = self.api
 
         ip.ex("import %s; reload(%s); from %s import *" % (
 
         arg,arg,arg)
 
         )
 
     ip.expose_magic('impall', doimp)
 
 You can also define your own aliased names for magic functions. In your
 ipythonrc file, placing a line like::
 
     execute __IP.magic_cl = __IP.magic_clear
 
 will define %cl as a new name for %clear.
 
 Type %magic for more information, including a list of all available
 magic functions at any time and their docstrings. You can also type
 %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
 information on the '?' system) to get information about any particular
 magic function you are interested in.
 
 The API documentation for the :mod:`IPython.Magic` module contains the full
 docstrings of all currently available magic commands.
 
 
 Access to the standard Python help
 ----------------------------------
 
 As of Python 2.1, a help system is available with access to object docstrings
 and the Python manuals. Simply type 'help' (no quotes) to access it. You can
 also type help(object) to obtain information about a given object, and
 help('keyword') for information on a keyword. As noted :ref:`here
 <accessing_help>`, you need to properly configure your environment variable
 PYTHONDOCS for this feature to work correctly.
 
 .. _dynamic_object_info:
 
 Dynamic object information
 --------------------------
 
 Typing ?word or word? prints detailed information about an object. If
 certain strings in the object are too long (docstrings, code, etc.) they
 get snipped in the center for brevity. This system gives access variable
 types and values, full source code for any object (if available),
 function prototypes and other useful information.
 
 Typing ??word or word?? gives access to the full information without
 snipping long strings. Long strings are sent to the screen through the
 less pager if longer than the screen and printed otherwise. On systems
 lacking the less command, IPython uses a very basic internal pager.
 
 The following magic functions are particularly useful for gathering
 information about your working environment. You can get more details by
 typing %magic or querying them individually (use %function_name? with or
 without the %), this is just a summary:
 
     * **%pdoc <object>**: Print (or run through a pager if too long) the
       docstring for an object. If the given object is a class, it will
       print both the class and the constructor docstrings.
     * **%pdef <object>**: Print the definition header for any callable
       object. If the object is a class, print the constructor information.
     * **%psource <object>**: Print (or run through a pager if too long)
       the source code for an object.
     * **%pfile <object>**: Show the entire source file where an object was
       defined via a pager, opening it at the line where the object
       definition begins.
     * **%who/%whos**: These functions give information about identifiers
       you have defined interactively (not things you loaded or defined
       in your configuration files). %who just prints a list of
       identifiers and %whos prints a table with some basic details about
       each identifier.
 
 Note that the dynamic object information functions (?/??, %pdoc, %pfile,
 %pdef, %psource) give you access to documentation even on things which
 are not really defined as separate identifiers. Try for example typing
 {}.get? or after doing import os, type os.path.abspath??.
 
 
 .. _readline:
 
 Readline-based features
 -----------------------
 
 These features require the GNU readline library, so they won't work if
 your Python installation lacks readline support. We will first describe
 the default behavior IPython uses, and then how to change it to suit
 your preferences.
 
 
 Command line completion
 +++++++++++++++++++++++
 
 At any time, hitting TAB will complete any available python commands or
 variable names, and show you a list of the possible completions if
 there's no unambiguous one. It will also complete filenames in the
 current directory if no python names match what you've typed so far.
 
 
 Search command history
 ++++++++++++++++++++++
 
 IPython provides two ways for searching through previous input and thus
 reduce the need for repetitive typing:
 
    1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
       (next,down) to search through only the history items that match
       what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
       prompt, they just behave like normal arrow keys.
    2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
       searches your history for lines that contain what you've typed so
       far, completing as much as it can.
 
 
 Persistent command history across sessions
 ++++++++++++++++++++++++++++++++++++++++++
 
 IPython will save your input history when it leaves and reload it next
 time you restart it. By default, the history file is named
 $IPYTHONDIR/history, but if you've loaded a named profile,
 '-PROFILE_NAME' is appended to the name. This allows you to keep
 separate histories related to various tasks: commands related to
 numerical work will not be clobbered by a system shell history, for
 example.
 
 
 Autoindent
 ++++++++++
 
 IPython can recognize lines ending in ':' and indent the next line,
 while also un-indenting automatically after 'raise' or 'return'.
 
 This feature uses the readline library, so it will honor your ~/.inputrc
 configuration (or whatever file your INPUTRC variable points to). Adding
 the following lines to your .inputrc file can make indenting/unindenting
 more convenient (M-i indents, M-u unindents)::
 
     $if Python 
     "\M-i": "    "  
     "\M-u": "\d\d\d\d"  
     $endif
 
 Note that there are 4 spaces between the quote marks after "M-i" above.
 
 Warning: this feature is ON by default, but it can cause problems with
 the pasting of multi-line indented code (the pasted code gets
 re-indented on each line). A magic function %autoindent allows you to
 toggle it on/off at runtime. You can also disable it permanently on in
 your ipythonrc file (set autoindent 0).
 
 
 Customizing readline behavior
 +++++++++++++++++++++++++++++
 
 All these features are based on the GNU readline library, which has an
 extremely customizable interface. Normally, readline is configured via a
 file which defines the behavior of the library; the details of the
 syntax for this can be found in the readline documentation available
 with your system or on the Internet. IPython doesn't read this file (if
 it exists) directly, but it does support passing to readline valid
 options via a simple interface. In brief, you can customize readline by
 setting the following options in your ipythonrc configuration file (note
 that these options can not be specified at the command line):
 
     * **readline_parse_and_bind**: this option can appear as many times as
       you want, each time defining a string to be executed via a
       readline.parse_and_bind() command. The syntax for valid commands
       of this kind can be found by reading the documentation for the GNU
       readline library, as these commands are of the kind which readline
       accepts in its configuration file.
     * **readline_remove_delims**: a string of characters to be removed
       from the default word-delimiters list used by readline, so that
       completions may be performed on strings which contain them. Do not
       change the default value unless you know what you're doing.
     * **readline_omit__names**: when tab-completion is enabled, hitting
       <tab> after a '.' in a name will complete all attributes of an
       object, including all the special methods whose names include
       double underscores (like __getitem__ or __class__). If you'd
       rather not see these names by default, you can set this option to
       1. Note that even when this option is set, you can still see those
       names by explicitly typing a _ after the period and hitting <tab>:
       'name._<tab>' will always complete attribute names starting with '_'.
       
       This option is off by default so that new users see all
       attributes of any objects they are dealing with.
 
 You will find the default values along with a corresponding detailed
 explanation in your ipythonrc file.
 
 
 Session logging and restoring
 -----------------------------
 
 You can log all input from a session either by starting IPython with the
 command line switches -log or -logfile (see :ref:`here <command_line_options>`)
 or by activating the logging at any moment with the magic function %logstart.
 
 Log files can later be reloaded with the -logplay option and IPython
 will attempt to 'replay' the log by executing all the lines in it, thus
 restoring the state of a previous session. This feature is not quite
 perfect, but can still be useful in many cases.
 
 The log files can also be used as a way to have a permanent record of
 any code you wrote while experimenting. Log files are regular text files
 which you can later open in your favorite text editor to extract code or
 to 'clean them up' before using them to replay a session.
 
 The %logstart function for activating logging in mid-session is used as
 follows:
 
 %logstart [log_name [log_mode]]
 
 If no name is given, it defaults to a file named 'log' in your
 IPYTHONDIR directory, in 'rotate' mode (see below).
 
 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
 history up to that point and then continues logging.
 
 %logstart takes a second optional parameter: logging mode. This can be
 one of (note that the modes are given unquoted):
 
     * [over:] overwrite existing log_name.
     * [backup:] rename (if exists) to log_name~ and start log_name.
     * [append:] well, that says it.
     * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
 
 The %logoff and %logon functions allow you to temporarily stop and
 resume logging to a file which had previously been started with
 %logstart. They will fail (with an explanation) if you try to use them
 before logging has been started.
 
 .. _system_shell_access:
 
 System shell access
 -------------------
 
 Any input line beginning with a ! character is passed verbatim (minus
 the !, of course) to the underlying operating system. For example,
 typing !ls will run 'ls' in the current directory.
 
 Manual capture of command output
 --------------------------------
 
 If the input line begins with two exclamation marks, !!, the command is
 executed but its output is captured and returned as a python list, split
 on newlines. Any output sent by the subprocess to standard error is
 printed separately, so that the resulting list only captures standard
 output. The !! syntax is a shorthand for the %sx magic command.
 
 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
 but allowing more fine-grained control of the capture details, and
 storing the result directly into a named variable. The direct use of 
 %sc is now deprecated, and you should ise the ``var = !cmd`` syntax
 instead.
 
 IPython also allows you to expand the value of python variables when
 making system calls. Any python variable or expression which you prepend
 with $ will get expanded before the system call is made::
 
     In [1]: pyvar='Hello world' 
     In [2]: !echo "A python variable: $pyvar"  
     A python variable: Hello world
 
 If you want the shell to actually see a literal $, you need to type it
 twice::
 
     In [3]: !echo "A system variable: $$HOME"  
     A system variable: /home/fperez
 
 You can pass arbitrary expressions, though you'll need to delimit them
 with {} if there is ambiguity as to the extent of the expression::
 
     In [5]: x=10 
     In [6]: y=20 
     In [13]: !echo $x+y  
     10+y  
     In [7]: !echo ${x+y}  
     30
 
 Even object attributes can be expanded::
 
     In [12]: !echo $sys.argv  
     [/home/fperez/usr/bin/ipython]
 
 
 System command aliases
 ----------------------
 
 The %alias magic function and the alias option in the ipythonrc
 configuration file allow you to define magic functions which are in fact
 system shell commands. These aliases can have parameters.
 
 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
 Then, typing '%alias_name params' will execute the system command 'cmd
 params' (from your underlying operating system).
 
 You can also define aliases with parameters using %s specifiers (one per
 parameter). The following example defines the %parts function as an
 alias to the command 'echo first %s second %s' where each %s will be
 replaced by a positional parameter to the call to %parts::
 
     In [1]: alias parts echo first %s second %s 
     In [2]: %parts A B 
     first A second B  
     In [3]: %parts A  
     Incorrect number of arguments: 2 expected.  
     parts is an alias to: 'echo first %s second %s'
 
 If called with no parameters, %alias prints the table of currently
 defined aliases.
 
 The %rehash/rehashx magics allow you to load your entire $PATH as
 ipython aliases. See their respective docstrings (or sec. 6.2
 <#sec:magic> for further details).
 
 
 .. _dreload:
 
 Recursive reload
 ----------------
 
 The dreload function does a recursive reload of a module: changes made
 to the module since you imported will actually be available without
 having to exit.
 
 
 Verbose and colored exception traceback printouts
 -------------------------------------------------
 
 IPython provides the option to see very detailed exception tracebacks,
 which can be especially useful when debugging large programs. You can
 run any Python file with the %run function to benefit from these
 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
 be colored (if your terminal supports it) which makes them much easier
 to parse visually.
 
 See the magic xmode and colors functions for details (just type %magic).
 
 These features are basically a terminal version of Ka-Ping Yee's cgitb
 module, now part of the standard Python library.
 
 
 .. _input_caching:
 
 Input caching system
 --------------------
 
 IPython offers numbered prompts (In/Out) with input and output caching
 (also referred to as 'input history'). All input is saved and can be 
 retrieved as variables (besides the usual arrow key recall), in 
 addition to the %rep magic command that brings a history entry
 up for editing on the next  command line.
 
 The following GLOBAL variables always exist (so don't overwrite them!):
 _i: stores previous input. _ii: next previous. _iii: next-next previous.
 _ih : a list of all input _ih[n] is the input from line n and this list
 is aliased to the global variable In. If you overwrite In with a
 variable of your own, you can remake the assignment to the internal list
 with a simple 'In=_ih'.
 
 Additionally, global variables named _i<n> are dynamically created (<n>
 being the prompt counter), such that
 _i<n> == _ih[<n>] == In[<n>].
 
 For example, what you typed at prompt 14 is available as _i14, _ih[14]
 and In[14].
 
 This allows you to easily cut and paste multi line interactive prompts
 by printing them out: they print like a clean string, without prompt
 characters. You can also manipulate them like regular variables (they
 are strings), modify or exec them (typing 'exec _i9' will re-execute the
 contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
 9 through 13 and line 18).
 
 You can also re-execute multiple lines of input easily by using the
 magic %macro function (which automates the process and allows
 re-execution without having to type 'exec' every time). The macro system
 also allows you to re-execute previous lines which include magic
 function calls (which require special processing). Type %macro? or see
 sec. 6.2 <#sec:magic> for more details on the macro system.
 
 A history function %hist allows you to see any part of your input
 history by printing a range of the _i variables.
 
 You can also search ('grep') through your history by typing 
 '%hist -g somestring'. This also searches through the so called *shadow history*,
 which remembers all the commands (apart from multiline code blocks)
 you have ever entered. Handy for searching for svn/bzr URL's, IP adrresses
 etc. You can bring shadow history entries listed by '%hist -g' up for editing 
 (or re-execution by just pressing ENTER) with %rep command. Shadow history 
 entries are not available as _iNUMBER variables, and they are identified by 
 the '0' prefix in %hist -g output. That is, history entry 12 is a normal 
 history entry, but 0231 is a shadow history entry.
 
 Shadow history was added because the readline history is inherently very
 unsafe - if you have multiple IPython sessions open, the last session 
 to close will overwrite the history of previountly closed session. Likewise,
 if a crash occurs, history is never saved, whereas shadow history entries
 are added after entering every command (so a command executed 
 in another IPython session is immediately available in other IPython 
 sessions that are open).
 
 To conserve space, a command can exist in shadow history only once - it doesn't 
 make sense to store a common line like "cd .." a thousand times. The idea is 
 mainly to provide a reliable place where valuable, hard-to-remember commands can 
 always be retrieved, as opposed to providing an exact sequence of commands
 you have entered in actual order.
 
 Because shadow history has all the commands you have ever executed,
 time taken by %hist -g will increase oven time. If it ever starts to take
 too long (or it ends up containing sensitive information like passwords), 
 clear the shadow history by `%clear shadow_nuke`.
 
 Time taken to add entries to shadow history should be negligible, but 
 in any case, if you start noticing performance degradation after using 
 IPython for a long time (or running a script that floods the shadow history!), 
 you can 'compress' the shadow history by executing 
 `%clear shadow_compress`. In practice, this should never be necessary
 in normal use.
 
 .. _output_caching:
 
 Output caching system
 ---------------------
 
 For output that is returned from actions, a system similar to the input
 cache exists but using _ instead of _i. Only actions that produce a
 result (NOT assignments, for example) are cached. If you are familiar
 with Mathematica, IPython's _ variables behave exactly like
 Mathematica's % variables.
 
 The following GLOBAL variables always exist (so don't overwrite them!):
 
     * [_] (a single underscore) : stores previous output, like Python's
       default interpreter.
     * [__] (two underscores): next previous.
     * [___] (three underscores): next-next previous.
 
 Additionally, global variables named _<n> are dynamically created (<n>
 being the prompt counter), such that the result of output <n> is always
 available as _<n> (don't use the angle brackets, just the number, e.g.
 _21).
 
 These global variables are all stored in a global dictionary (not a
 list, since it only has entries for lines which returned a result)
 available under the names _oh and Out (similar to _ih and In). So the
 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
 accidentally overwrite the Out variable you can recover it by typing
 'Out=_oh' at the prompt.
 
 This system obviously can potentially put heavy memory demands on your
 system, since it prevents Python's garbage collector from removing any
 previously computed results. You can control how many results are kept
 in memory with the option (at the command line or in your ipythonrc
 file) cache_size. If you set it to 0, the whole system is completely
 disabled and the prompts revert to the classic '>>>' of normal Python.
 
 
 Directory history
 -----------------
 
 Your history of visited directories is kept in the global list _dh, and
 the magic %cd command can be used to go to any entry in that list. The
 %dhist command allows you to view this history. Do ``cd -<TAB`` to
 conventiently view the directory history.
 
 
 Automatic parentheses and quotes
 --------------------------------
 
 These features were adapted from Nathan Gray's LazyPython. They are
 meant to allow less typing for common situations.
 
 
 Automatic parentheses
 ---------------------
 
 Callable objects (i.e. functions, methods, etc) can be invoked like this
 (notice the commas between the arguments)::
 
     >>> callable_ob arg1, arg2, arg3
 
 and the input will be translated to this::
 
     -> callable_ob(arg1, arg2, arg3)
 
 You can force automatic parentheses by using '/' as the first character
 of a line. For example::
 
     >>> /globals # becomes 'globals()'
 
 Note that the '/' MUST be the first character on the line! This won't work::
 
     >>> print /globals # syntax error
 
 In most cases the automatic algorithm should work, so you should rarely
 need to explicitly invoke /. One notable exception is if you are trying
 to call a function with a list of tuples as arguments (the parenthesis
 will confuse IPython)::
 
     In [1]: zip (1,2,3),(4,5,6) # won't work
 
 but this will work::
 
     In [2]: /zip (1,2,3),(4,5,6) 
     ---> zip ((1,2,3),(4,5,6))  
     Out[2]= [(1, 4), (2, 5), (3, 6)]
 
 IPython tells you that it has altered your command line by displaying
 the new command line preceded by ->. e.g.::
 
     In [18]: callable list 
     ----> callable (list)
 
 
 Automatic quoting
 -----------------
 
 You can force automatic quoting of a function's arguments by using ','
 or ';' as the first character of a line. For example::
 
     >>> ,my_function /home/me # becomes my_function("/home/me")
 
 If you use ';' instead, the whole argument is quoted as a single string
 (while ',' splits on whitespace)::
 
     >>> ,my_function a b c # becomes my_function("a","b","c")
 
     >>> ;my_function a b c # becomes my_function("a b c")
 
 Note that the ',' or ';' MUST be the first character on the line! This
 won't work::
 
     >>> x = ,my_function /home/me # syntax error
 
 IPython as your default Python environment
 ==========================================
 
 Python honors the environment variable PYTHONSTARTUP and will execute at
 startup the file referenced by this variable. If you put at the end of
 this file the following two lines of code::
 
     import IPython 
     IPython.Shell.IPShell().mainloop(sys_exit=1)
 
 then IPython will be your working environment anytime you start Python.
 The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
 it finishes, otherwise you'll be back at the normal Python '>>>'
 prompt.
 
 This is probably useful to developers who manage multiple Python
 versions and don't want to have correspondingly multiple IPython
 versions. Note that in this mode, there is no way to pass IPython any
 command-line options, as those are trapped first by Python itself.
 
 .. _Embedding:
 
 Embedding IPython
 =================
 
 It is possible to start an IPython instance inside your own Python
 programs. This allows you to evaluate dynamically the state of your
 code, operate with your variables, analyze them, etc. Note however that
 any changes you make to values while in the shell do not propagate back
 to the running code, so it is safe to modify your values because you
 won't break your code in bizarre ways by doing so.
 
 This feature allows you to easily have a fully functional python
 environment for doing object introspection anywhere in your code with a
 simple function call. In some cases a simple print statement is enough,
 but if you need to do more detailed analysis of a code fragment this
 feature can be very valuable.
 
 It can also be useful in scientific computing situations where it is
 common to need to do some automatic, computationally intensive part and
 then stop to look at data, plots, etc.
 Opening an IPython instance will give you full access to your data and
 functions, and you can resume program execution once you are done with
 the interactive part (perhaps to stop again later, as many times as
 needed).
 
 The following code snippet is the bare minimum you need to include in
 your Python programs for this to work (detailed examples follow later)::
 
     from IPython.Shell import IPShellEmbed
 
     ipshell = IPShellEmbed()
 
     ipshell() # this call anywhere in your program will start IPython
 
 You can run embedded instances even in code which is itself being run at
 the IPython interactive prompt with '%run <filename>'. Since it's easy
 to get lost as to where you are (in your top-level IPython or in your
 embedded one), it's a good idea in such cases to set the in/out prompts
 to something different for the embedded instances. The code examples
 below illustrate this.
 
 You can also have multiple IPython instances in your program and open
 them separately, for example with different options for data
 presentation. If you close and open the same instance multiple times,
 its prompt counters simply continue from each execution to the next.
 
 Please look at the docstrings in the Shell.py module for more details on
 the use of this system.
 
 The following sample file illustrating how to use the embedding
 functionality is provided in the examples directory as example-embed.py.
 It should be fairly self-explanatory::
 
 
     #!/usr/bin/env python
 
     """An example of how to embed an IPython shell into a running program.
 
     Please see the documentation in the IPython.Shell module for more details.
 
     The accompanying file example-embed-short.py has quick code fragments for
     embedding which you can cut and paste in your code once you understand how
     things work.
 
     The code in this file is deliberately extra-verbose, meant for learning."""
 
     # The basics to get you going:
 
     # IPython sets the __IPYTHON__ variable so you can know if you have nested
     # copies running.
 
     # Try running this code both at the command line and from inside IPython (with
     # %run example-embed.py)
     try:
         __IPYTHON__
     except NameError:
         nested = 0
         args = ['']
     else:
         print "Running nested copies of IPython."
         print "The prompts for the nested copy have been modified"
         nested = 1
         # what the embedded instance will see as sys.argv:
         args = ['-pi1','In <\\#>: ','-pi2','   .\\D.: ',
                 '-po','Out<\\#>: ','-nosep']
 
     # First import the embeddable shell class
     from IPython.Shell import IPShellEmbed
 
     # Now create an instance of the embeddable shell. The first argument is a
     # string with options exactly as you would type them if you were starting
     # IPython at the system command line. Any parameters you want to define for
     # configuration can thus be specified here.
     ipshell = IPShellEmbed(args,
                            banner = 'Dropping into IPython',
                            exit_msg = 'Leaving Interpreter, back to program.')
 
     # Make a second instance, you can have as many as you want.
     if nested:
         args[1] = 'In2<\\#>'
     else:
         args = ['-pi1','In2<\\#>: ','-pi2','   .\\D.: ',
                 '-po','Out<\\#>: ','-nosep']
     ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
 
     print '\nHello. This is printed from the main controller program.\n'
 
     # You can then call ipshell() anywhere you need it (with an optional
     # message):
     ipshell('***Called from top level. '
             'Hit Ctrl-D to exit interpreter and continue program.\n'
             'Note that if you use %kill_embedded, you can fully deactivate\n'
             'This embedded instance so it will never turn on again')
 
     print '\nBack in caller program, moving along...\n'
 
     #---------------------------------------------------------------------------
     # More details:
 
     # IPShellEmbed instances don't print the standard system banner and
     # messages. The IPython banner (which actually may contain initialization
     # messages) is available as <instance>.IP.BANNER in case you want it.
 
     # IPShellEmbed instances print the following information everytime they
     # start:
 
     # - A global startup banner.
 
     # - A call-specific header string, which you can use to indicate where in the
     # execution flow the shell is starting.
 
     # They also print an exit message every time they exit.
 
     # Both the startup banner and the exit message default to None, and can be set
     # either at the instance constructor or at any other time with the
     # set_banner() and set_exit_msg() methods.
 
     # The shell instance can be also put in 'dummy' mode globally or on a per-call
     # basis. This gives you fine control for debugging without having to change
     # code all over the place.
 
     # The code below illustrates all this.
 
 
     # This is how the global banner and exit_msg can be reset at any point
     ipshell.set_banner('Entering interpreter - New Banner')
     ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
 
     def foo(m):
         s = 'spam'
         ipshell('***In foo(). Try @whos, or print s or m:')
         print 'foo says m = ',m
 
     def bar(n):
         s = 'eggs'
         ipshell('***In bar(). Try @whos, or print s or n:')
         print 'bar says n = ',n
 
     # Some calls to the above functions which will trigger IPython:
     print 'Main program calling foo("eggs")\n'
     foo('eggs')
 
     # The shell can be put in 'dummy' mode where calls to it silently return. This
     # allows you, for example, to globally turn off debugging for a program with a
     # single call.
     ipshell.set_dummy_mode(1)
     print '\nTrying to call IPython which is now "dummy":'
     ipshell()
     print 'Nothing happened...'
     # The global 'dummy' mode can still be overridden for a single call
     print '\nOverriding dummy mode manually:'
     ipshell(dummy=0)
 
     # Reactivate the IPython shell
     ipshell.set_dummy_mode(0)
 
     print 'You can even have multiple embedded instances:'
     ipshell2()
 
     print '\nMain program calling bar("spam")\n'
     bar('spam')
 
     print 'Main program finished. Bye!'
 
     #********************** End of file <example-embed.py> ***********************
 
 Once you understand how the system functions, you can use the following
 code fragments in your programs which are ready for cut and paste::
 
 
     """Quick code snippets for embedding IPython into other programs.
 
     See example-embed.py for full details, this file has the bare minimum code for
     cut and paste use once you understand how to use the system."""
 
     #---------------------------------------------------------------------------
     # This code loads IPython but modifies a few things if it detects it's running
     # embedded in another IPython session (helps avoid confusion)
 
     try:
         __IPYTHON__
     except NameError:
         argv = ['']
         banner = exit_msg = ''
     else:
         # Command-line options for IPython (a list like sys.argv)
         argv = ['-pi1','In <\\#>:','-pi2','   .\\D.:','-po','Out<\\#>:']
         banner = '*** Nested interpreter ***'
         exit_msg = '*** Back in main IPython ***'
 
     # First import the embeddable shell class
     from IPython.Shell import IPShellEmbed
     # Now create the IPython shell instance. Put ipshell() anywhere in your code
     # where you want it to open.
     ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
 
     #---------------------------------------------------------------------------
     # This code will load an embeddable IPython shell always with no changes for
     # nested embededings.
 
     from IPython.Shell import IPShellEmbed
     ipshell = IPShellEmbed()
     # Now ipshell() will open IPython anywhere in the code.
 
     #---------------------------------------------------------------------------
     # This code loads an embeddable shell only if NOT running inside
     # IPython. Inside IPython, the embeddable shell variable ipshell is just a
     # dummy function.
 
     try:
         __IPYTHON__
     except NameError:
         from IPython.Shell import IPShellEmbed
         ipshell = IPShellEmbed()
         # Now ipshell() will open IPython anywhere in the code
     else:
         # Define a dummy ipshell() so the same code doesn't crash inside an
         # interactive IPython
         def ipshell(): pass
 
     #******************* End of file <example-embed-short.py> ********************
 
 Using the Python debugger (pdb)
 ===============================
 
 Running entire programs via pdb
 -------------------------------
 
 pdb, the Python debugger, is a powerful interactive debugger which
 allows you to step through code, set breakpoints, watch variables,
 etc.  IPython makes it very easy to start any script under the control
 of pdb, regardless of whether you have wrapped it into a 'main()'
 function or not. For this, simply type '%run -d myscript' at an
 IPython prompt. See the %run command's documentation (via '%run?' or
 in Sec. magic_ for more details, including how to control where pdb
 will stop execution first.
 
 For more information on the use of the pdb debugger, read the included
 pdb.doc file (part of the standard Python distribution). On a stock
 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
 easiest way to read it is by using the help() function of the pdb module
 as follows (in an IPython prompt):
 
 In [1]: import pdb 
 In [2]: pdb.help()
 
 This will load the pdb.doc document in a file viewer for you automatically.
 
 
 Automatic invocation of pdb on exceptions
 -----------------------------------------
 
 IPython, if started with the -pdb option (or if the option is set in
 your rc file) can call the Python pdb debugger every time your code
 triggers an uncaught exception. This feature
 can also be toggled at any time with the %pdb magic command. This can be
 extremely useful in order to find the origin of subtle bugs, because pdb
 opens up at the point in your code which triggered the exception, and
 while your program is at this point 'dead', all the data is still
 available and you can walk up and down the stack frame and understand
 the origin of the problem.
 
 Furthermore, you can use these debugging facilities both with the
 embedded IPython mode and without IPython at all. For an embedded shell
 (see sec. Embedding_), simply call the constructor with
 '-pdb' in the argument string and automatically pdb will be called if an
 uncaught exception is triggered by your code.
 
 For stand-alone use of the feature in your programs which do not use
 IPython at all, put the following lines toward the top of your 'main'
 routine::
 
     import sys
     from IPython.core import ultratb
     sys.excepthook = ultratb.FormattedTB(mode='Verbose',
     color_scheme='Linux', call_pdb=1)
 
 The mode keyword can be either 'Verbose' or 'Plain', giving either very
 detailed or normal tracebacks respectively. The color_scheme keyword can
 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
 options which can be set in IPython with -colors and -xmode.
 
 This will give any of your programs detailed, colored tracebacks with
 automatic invocation of pdb.
 
 
 Extensions for syntax processing
 ================================
 
 This isn't for the faint of heart, because the potential for breaking
 things is quite high. But it can be a very powerful and useful feature.
 In a nutshell, you can redefine the way IPython processes the user input
 line to accept new, special extensions to the syntax without needing to
 change any of IPython's own code.
 
 In the IPython/extensions directory you will find some examples
 supplied, which we will briefly describe now. These can be used 'as is'
 (and both provide very useful functionality), or you can use them as a
 starting point for writing your own extensions.
 
 
 Pasting of code starting with '>>> ' or '... '
 ----------------------------------------------
 
 In the python tutorial it is common to find code examples which have
 been taken from real python sessions. The problem with those is that all
 the lines begin with either '>>> ' or '... ', which makes it impossible
 to paste them all at once. One must instead do a line by line manual
 copying, carefully removing the leading extraneous characters.
 
 This extension identifies those starting characters and removes them
 from the input automatically, so that one can paste multi-line examples
 directly into IPython, saving a lot of time. Please look at the file
 InterpreterPasteInput.py in the IPython/extensions directory for details
 on how this is done.
 
 IPython comes with a special profile enabling this feature, called
 tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
 will be available. In a normal IPython session you can activate the
 feature by importing the corresponding module with:
 In [1]: import IPython.extensions.InterpreterPasteInput
 
 The following is a 'screenshot' of how things work when this extension
 is on, copying an example from the standard tutorial::
 
     IPython profile: tutorial 
 
     *** Pasting of code with ">>>" or "..." has been enabled. 
 
     In [1]: >>> def fib2(n): # return Fibonacci series up to n 
        ...: ...     """Return a list containing the Fibonacci series up to
     n.""" 
        ...: ...     result = [] 
        ...: ...     a, b = 0, 1 
        ...: ...     while b < n: 
        ...: ...         result.append(b)    # see below 
        ...: ...         a, b = b, a+b 
        ...: ...     return result 
        ...: 
 
     In [2]: fib2(10) 
     Out[2]: [1, 1, 2, 3, 5, 8]
 
 Note that as currently written, this extension does not recognize
 IPython's prompts for pasting. Those are more complicated, since the
 user can change them very easily, they involve numbers and can vary in
 length. One could however extract all the relevant information from the
 IPython instance and build an appropriate regular expression. This is
 left as an exercise for the reader.
 
 
 Input of physical quantities with units
 ---------------------------------------
 
 The module PhysicalQInput allows a simplified form of input for physical
 quantities with units. This file is meant to be used in conjunction with
 the PhysicalQInteractive module (in the same directory) and
 Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
 (http://dirac.cnrs-orleans.fr/ScientificPython/).
 
 The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
 but these must be declared as instances of a class. For example, to
 define v as a velocity of 3 m/s, normally you would write::
 
     In [1]: v = PhysicalQuantity(3,'m/s')
 
 Using the PhysicalQ_Input extension this can be input instead as: 
 In [1]: v = 3 m/s
 which is much more convenient for interactive use (even though it is
 blatantly invalid Python syntax).
 
 The physics profile supplied with IPython (enabled via 'ipython -p
 physics') uses these extensions, which you can also activate with:
 
 from math import * # math MUST be imported BEFORE PhysicalQInteractive 
 from IPython.extensions.PhysicalQInteractive import * 
 import IPython.extensions.PhysicalQInput
 
 .. _gui_support:
 
 GUI event loop support support
 ==============================
 
 .. versionadded:: 0.11
     The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
 
 IPython has excellent support for working interactively with Graphical User
 Interface (GUI) toolkits, such as wxPython, PyQt4, PyGTK and Tk. This is
 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
 is extremely robust compared to our previous threaded based version. The
 advantages of this are:
 
 * GUIs can be enabled and disabled dynamically at runtime.
 * The active GUI can be switched dynamically at runtime.
 * In some cases, multiple GUIs can run simultaneously with no problems.
 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing 
   all of these things.
 
 For users, enabling GUI event loop integration is simple.  You simple use the
 ``%gui`` magic as follows::
 
     %gui [-a] [GUINAME]
 
 With no arguments, ``%gui`` removes all GUI support.  Valid ``GUINAME``
 arguments are ``wx``, ``qt4``, ``gtk`` and ``tk``.  The ``-a`` option will
 create and return a running application object for the selected GUI toolkit.
 
 Thus, to use wxPython interactively and create a running :class:`wx.App`
 object, do::
 
     %gui -a wx
 
 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
 see :ref:`this section <matplotlib_support>`.
 
 For developers that want to use IPython's GUI event loop integration in
 the form of a library, these capabilities are exposed in library form
 in the :mod:`IPython.lib.inputhook`.  Interested developers should see the
 module docstrings for more information, but there are a few points that
 should be mentioned here.
 
 First, the ``PyOSInputHook`` approach only works in command line settings 
 where readline is activated.
 
 Second, when using the ``PyOSInputHook`` approach, a GUI application should
 *not* start its event loop. Instead all of this is handled by the
 ``PyOSInputHook``. This means that applications that are meant to be used both
 in IPython and as standalone apps need to have special code to detects how the
 application is being run. We highly recommend using IPython's
 :func:`appstart_` functions for this. Here is a simple example that shows the
 recommended code that should be at the bottom of a wxPython using GUI
 application::
 
   try:
       from IPython import appstart_wx
       appstart_wx(app)
   except ImportError:
       app.MainLoop()
 
 This pattern should be used instead of the simple ``app.MainLoop()`` code
 that a standalone wxPython application would have.
 
 Third, unlike previous versions of IPython, we no longer "hijack" (replace
 them with no-ops) the event loops. This is done to allow applications that
 actually need to run the real event loops to do so. This is often needed to
 process pending events at critical points.
 
 Finally, we also have a number of examples in our source directory
 :file:`docs/examples/lib` that demonstrate these capabilities.
 
 .. _matplotlib_support:
 
 Plotting with matplotlib
 ========================
 
 
 `Matplotlib`_ provides high quality 2D and
 3D plotting for Python. Matplotlib can produce plots on screen using a variety
 of GUI toolkits, including Tk, PyGTK, PyQt4 and wxPython. It also provides a
 number of commands useful for scientific computing, all with a syntax
 compatible with that of the popular Matlab program.
 
 Many IPython users have come to rely on IPython's ``-pylab`` mode which
 automates the integration of Matplotlib with IPython. We are still in the
 process of working with the Matplotlib developers to finalize the new pylab
 API, but for now you can use Matplotlib interactively using the following
 commands::
 
     %gui -a wx
     import matplotlib
     matplotlib.use('wxagg')
     from matplotlib import pylab
     pylab.interactive(True)
 
 All of this will soon be automated as Matplotlib beings to include
 new logic that uses our new GUI support.
 
 .. _interactive_demos:
 
 Interactive demos with IPython
 ==============================
 
 IPython ships with a basic system for running scripts interactively in
 sections, useful when presenting code to audiences. A few tags embedded
 in comments (so that the script remains valid Python code) divide a file
 into separate blocks, and the demo can be run one block at a time, with
 IPython printing (with syntax highlighting) the block before executing
 it, and returning to the interactive prompt after each block. The
 interactive namespace is updated after each block is run with the
 contents of the demo's namespace.
 
 This allows you to show a piece of code, run it and then execute
 interactively commands based on the variables just created. Once you
 want to continue, you simply execute the next block of the demo. The
 following listing shows the markup necessary for dividing a script into
 sections for execution as a demo::
 
 
     """A simple interactive demo to illustrate the use of IPython's Demo class.
 
     Any python script can be run as a demo, but that does little more than showing
     it on-screen, syntax-highlighted in one shot.  If you add a little simple
     markup, you can stop at specified intervals and return to the ipython prompt,
     resuming execution later.
     """
 
     print 'Hello, welcome to an interactive IPython demo.'
     print 'Executing this block should require confirmation before proceeding,'
     print 'unless auto_all has been set to true in the demo object'
 
     # The mark below defines a block boundary, which is a point where IPython will
     # stop execution and return to the interactive prompt.
     # Note that in actual interactive execution, 
     # <demo> --- stop ---
 
     x = 1
     y = 2
 
     # <demo> --- stop ---
 
     # the mark below makes this block as silent
     # <demo> silent
 
     print 'This is a silent block, which gets executed but not printed.'
 
     # <demo> --- stop ---
     # <demo> auto
     print 'This is an automatic block.'
     print 'It is executed without asking for confirmation, but printed.'
     z = x+y
 
     print 'z=',x
 
     # <demo> --- stop ---
     # This is just another normal block.
     print 'z is now:', z
 
     print 'bye!'
 
 In order to run a file as a demo, you must first make a Demo object out
 of it. If the file is named myscript.py, the following code will make a
 demo::
 
     from IPython.demo import Demo
 
     mydemo = Demo('myscript.py')
 
 This creates the mydemo object, whose blocks you run one at a time by
 simply calling the object with no arguments. If you have autocall active
 in IPython (the default), all you need to do is type::
 
     mydemo 
 
 and IPython will call it, executing each block. Demo objects can be
 restarted, you can move forward or back skipping blocks, re-execute the
 last block, etc. Simply use the Tab key on a demo object to see its
 methods, and call '?' on them to see their docstrings for more usage
 details. In addition, the demo module itself contains a comprehensive
 docstring, which you can access via::
 
     from IPython import demo
 
     demo?
 
 Limitations: It is important to note that these demos are limited to
 fairly simple uses. In particular, you can not put division marks in
 indented code (loops, if statements, function definitions, etc.)
 Supporting something like this would basically require tracking the
 internal execution state of the Python interpreter, so only top-level
 divisions are allowed. If you want to be able to open an IPython
 instance at an arbitrary point in a program, you can use IPython's
 embedding facilities, described in detail in Sec. 9
 
 .. [Matplotlib] Matplotlib. http://matplotlib.sourceforge.net
 

docs/source/interactive/shell.txt

@@ -1,285 +1,293 b''
 .. _ipython_as_shell:
 
 =========================
 IPython as a system shell
 =========================
 
+.. warning::
+
+    As of the 0.11 version of IPython, some of the features and APIs
+    described in this section have been deprecated or are broken.  Our plan
+    is to continue to support these features, but they need to be updated
+    to take advantage of recent API changes.  Furthermore, this section
+    of the documentation need to be updated to reflect all of these changes.
+
 Overview
 ========
 
 The 'sh' profile optimizes IPython for system shell usage. Apart from
 certain job control functionality that is present in unix (ctrl+z does
 "suspend"), the sh profile should provide you with most of the
 functionality you use daily in system shell, and more. Invoke IPython
 in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching
 the "pysh" shortcut in start menu.
 
 If you want to use the features of sh profile as your defaults (which
 might be a good idea if you use other profiles a lot of the time but
 still want the convenience of sh profile), add ``import ipy_profile_sh``
 to your ~/.ipython/ipy_user_conf.py.
 
 The 'sh' profile is different from the default profile in that:
 
  * Prompt shows the current directory
  * Spacing between prompts and input is more compact (no padding with
    empty lines). The startup banner is more compact as well.
  * System commands are directly available (in alias table) without
    requesting %rehashx - however, if you install new programs along
    your PATH, you might want to run %rehashx to update the persistent
    alias table
  * Macros are stored in raw format by default. That is, instead of
    '_ip.system("cat foo"), the macro will contain text 'cat foo')
  * Autocall is in full mode
  * Calling "up" does "cd .."
 
 The 'sh' profile is different from the now-obsolete (and unavailable)
 'pysh' profile in that:
 
  * '$$var = command' and '$var = command' syntax is not supported
  * anymore. Use 'var = !command' instead (incidentally, this is
  * available in all IPython profiles). Note that !!command *will*
  * work.
 
 Aliases
 =======
 
 All of your $PATH has been loaded as IPython aliases, so you should be
 able to type any normal system command and have it executed. See
 %alias?  and %unalias? for details on the alias facilities. See also
 %rehashx? for details on the mechanism used to load $PATH.
 
 
 Directory management
 ====================
 
 Since each command passed by ipython to the underlying system is executed
 in a subshell which exits immediately, you can NOT use !cd to navigate
 the filesystem.
 
 IPython provides its own builtin '%cd' magic command to move in the
 filesystem (the % is not required with automagic on). It also maintains
 a list of visited directories (use %dhist to see it) and allows direct
 switching to any of them. Type 'cd?' for more details.
 
 %pushd, %popd and %dirs are provided for directory stack handling.
 
 
 Enabled extensions
 ==================
 
 Some extensions, listed below, are enabled as default in this profile.
 
 envpersist
 ----------
 
 %env can be used to "remember" environment variable manipulations. Examples::
 
 	%env - Show all environment variables
 	%env VISUAL=jed  - set VISUAL to jed
 	%env PATH+=;/foo - append ;foo to PATH
 	%env PATH+=;/bar - also append ;bar to PATH
 	%env PATH-=/wbin; - prepend /wbin; to PATH
 	%env -d VISUAL   - forget VISUAL persistent val
 	%env -p          - print all persistent env modifications
 
 ipy_which
 ---------
 
 %which magic command. Like 'which' in unix, but knows about ipython aliases.
 
 Example::
 
  [C:/ipython]|14> %which st
  st -> start .
  [C:/ipython]|15> %which d
  d -> dir /w /og /on
  [C:/ipython]|16> %which cp
  cp -> cp
    == c:\bin\cp.exe
  c:\bin\cp.exe
 
 ipy_app_completers
 ------------------
 
 Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu.
 
 ipy_rehashdir
 -------------
 
 Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir::
 
  [~]|22> cd c:/opt/PuTTY/
  [c:opt/PuTTY]|23> rehashdir .
               <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000']
 
 Now, you can execute any of those commams directly::
 
  [c:opt/PuTTY]|24> cd
  [~]|25> putty
 
 (the putty window opens).
 
 If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop::
 
  [~]|27> for a in _23:
     |..>     %store $a
     |..>
     |..>
  Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe')
  Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe')
  Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe')
  Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe')
  ...
 
 mglob
 -----
 
 Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples::
 
  [c:/ipython]|9> mglob *.py
  [c:/ipython]|10> mglob *.py rec:*.txt
  [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:.
 
 Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'.
 
 
 Prompt customization
 ====================
 
 The sh profile uses the following prompt configurations::
 
     o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>'
     o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>'
 
 You can change the prompt configuration to your liking by editing
 ipy_user_conf.py.  
 
 String lists
 ============
 
 String lists (IPython.genutils.SList) are handy way to process output
 from system commands. They are produced by ``var = !cmd`` syntax.
 
 First, we acquire the output of 'ls -l'::
 
     [Q:doc/examples]|2> lines = !ls -l
      ==
     ['total 23',
      '-rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py',
      '-rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py',
      '-rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py',
      '-rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py',
      '-rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py',
      '-rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py',
      '-rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc']
 
 Now, let's take a look at the contents of 'lines' (the first number is
 the list element number)::
 
     [Q:doc/examples]|3> lines
                     <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
     0: total 23
     1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
     2: -rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py
     3: -rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py
     4: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
     5: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
     6: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
     7: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
 
 Now, let's filter out the 'embed' lines::
 
     [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1)
     [Q:doc/examples]|5> l2
                     <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
     0: total 23
     1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
     2: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
     3: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
     4: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
     5: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
 
 Now, we want strings having just file names and permissions::
 
     [Q:doc/examples]|6> l2.fields(8,0)
                     <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
     0: total
     1: example-demo.py -rw-rw-rw-
     2: example-gnuplot.py -rwxrwxrwx
     3: extension.py -rwxrwxrwx
     4: seteditor.py -rwxrwxrwx
     5: seteditor.pyc -rwxrwxrwx
 
 Note how the line with 'total' does not raise IndexError.
 
 If you want to split these (yielding lists), call fields() without
 arguments::
 
     [Q:doc/examples]|7> _.fields()
                     <7>
     [['total'],
      ['example-demo.py', '-rw-rw-rw-'],
      ['example-gnuplot.py', '-rwxrwxrwx'],
      ['extension.py', '-rwxrwxrwx'],
      ['seteditor.py', '-rwxrwxrwx'],
      ['seteditor.pyc', '-rwxrwxrwx']]
 
 If you want to pass these separated with spaces to a command (typical
 for lists if files), use the .s property::
 
 
     [Q:doc/examples]|13> files = l2.fields(8).s
     [Q:doc/examples]|14> files
                     <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc'
     [Q:doc/examples]|15> ls $files
     example-demo.py  example-gnuplot.py  extension.py  seteditor.py  seteditor.pyc
 
 SLists are inherited from normal python lists, so every list method is
 available::
 
     [Q:doc/examples]|21> lines.append('hey')
 
 
 Real world example: remove all files outside version control
 ============================================================
 
 First, capture output of "hg status"::
 
     [Q:/ipython]|28> out = !hg status
      ==
     ['M IPython\\extensions\\ipy_kitcfg.py',
      'M IPython\\extensions\\ipy_rehashdir.py',
     ...
      '? build\\lib\\IPython\\Debugger.py',
      '? build\\lib\\IPython\\extensions\\InterpreterExec.py',
      '? build\\lib\\IPython\\extensions\\InterpreterPasteInput.py',
     ...
 
 (lines starting with ? are not under version control).
 
 ::
 
     [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1)
     [Q:/ipython]|36> junk
                 <36> SList (.p, .n, .l, .s, .grep(), .fields() availab
     ...
     10: build\bdist.win32\winexe\temp\_ctypes.py
     11: build\bdist.win32\winexe\temp\_hashlib.py
     12: build\bdist.win32\winexe\temp\_socket.py
 
 Now we can just remove these files by doing 'rm $junk.s'. 
 
 The .s, .n, .p properties
 =========================
 
 The '.s' property returns one string where lines are separated by
 single space (for convenient passing to system commands). The '.n'
 property return one string where the lines are separated by '\n'
 (i.e. the original output of the function). If the items in string
 list are file names, '.p' can be used to get a list of "path" objects
 for convenient file manipulation.
 

docs/source/interactive/tutorial.txt

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

docs/source/overview.txt

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

docs/source/whatsnew/index.txt

@@ -1,23 +1,28 b''
 .. Developers should add in this file, during each release cycle, information
 .. about important changes they've made, in a summary format that's meant for
 .. end users.  For each release we normally have three sections: features,  bug
 .. fixes and api breakage.
 .. Please remember to credit the authors of the contributions by name,
 .. especially when they are new users or developers who do not regularly
 .. participate  in IPython's development.
 
 .. _whatsnew_index:
 
 =====================
 What's new in IPython
 =====================
 
+This section documents the changes that have been made in various versions of
+IPython. Users should consult these pages to learn about new features, bug
+fixes and backwards incompatibilities. Developers should summarize the
+development work they do here in a user friendly format.
+
 .. toctree::
    :maxdepth: 1
 
    development
    version0.10
    version0.9
    version0.8