update tornado dependency to 2.1

The notebook server will no longer try to launch with 2.0.

Test imports and install doc updated to match.

IPython/frontend/html/notebook/__init__.py

@@ -0,0 +1,12 b''
+"""The IPython HTML Notebook"""
+
+# check for tornado 2.1.0
+msg = "The IPython Notebook requires tornado >= 2.1.0"
+try:
+    import tornado
+except ImportError:
+    raise ImportError(msg)
+else:
+    if tornado.version_info < (2,1,0):
+        raise ImportError(msg+", but you have %s"%tornado.version)
+del msg

IPython/testing/iptest.py

@@ -1,441 +1,449 b''
 # -*- coding: utf-8 -*-
 """IPython Test Suite Runner.
 
 This module provides a main entry point to a user script to test IPython
 itself from the command line. There are two ways of running this script:
 
 1. With the syntax `iptest all`.  This runs our entire test suite by
    calling this script (with different arguments) recursively.  This
    causes modules and package to be tested in different processes, using nose
    or trial where appropriate.
 2. With the regular nose syntax, like `iptest -vvs IPython`.  In this form
    the script simply calls nose, but with special command line flags and
    plugins loaded.
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Stdlib
 import os
 import os.path as path
 import signal
 import sys
 import subprocess
 import tempfile
 import time
 import warnings
 
 # Note: monkeypatch!
 # We need to monkeypatch a small problem in nose itself first, before importing
 # it for actual use.  This should get into nose upstream, but its release cycle
 # is slow and we need it for our parametric tests to work correctly.
 from IPython.testing import nosepatch
 # Now, proceed to import nose itself
 import nose.plugins.builtin
 from nose.core import TestProgram
 
 # Our own imports
 from IPython.utils.path import get_ipython_module_path
 from IPython.utils.process import find_cmd, pycmd2argv
 from IPython.utils.sysinfo import sys_info
 
 from IPython.testing import globalipapp
 from IPython.testing.plugin.ipdoctest import IPythonDoctest
 from IPython.external.decorators import KnownFailure
 
 pjoin = path.join
 
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 
 
 #-----------------------------------------------------------------------------
 # Warnings control
 #-----------------------------------------------------------------------------
 
 # Twisted generates annoying warnings with Python 2.6, as will do other code
 # that imports 'sets' as of today
 warnings.filterwarnings('ignore', 'the sets module is deprecated',
                         DeprecationWarning )
 
 # This one also comes from Twisted
 warnings.filterwarnings('ignore', 'the sha module is deprecated',
                         DeprecationWarning)
 
 # Wx on Fedora11 spits these out
 warnings.filterwarnings('ignore', 'wxPython/wxWidgets release number mismatch',
                         UserWarning)
 
 #-----------------------------------------------------------------------------
 # Logic for skipping doctests
 #-----------------------------------------------------------------------------
 
 def test_for(mod, min_version=None):
     """Test to see if mod is importable."""
     try:
         __import__(mod)
     except (ImportError, RuntimeError):
         # GTK reports Runtime error if it can't be initialized even if  it's
         # importable.
         return False
     else:
         if min_version:
             return sys.modules[mod].__version__ >= min_version
         else:
             return True
 
 # Global dict where we can store information on what we have and what we don't
 # have available at test run time
 have = {}
 
 have['curses'] = test_for('_curses')
 have['matplotlib'] = test_for('matplotlib')
 have['pexpect'] = test_for('pexpect')
 have['pymongo'] = test_for('pymongo')
 have['wx'] = test_for('wx')
 have['wx.aui'] = test_for('wx.aui')
 if os.name == 'nt':
     have['zmq'] = test_for('zmq', '2.1.7')
 else:
     have['zmq'] = test_for('zmq', '2.1.4')
 have['qt'] = test_for('IPython.external.qt')
-have['tornado'] = test_for('tornado')
+
+try:
+    import tornado
+    if tornado.version_info < (2,1,0):
+        raise ImportError
+except ImportError:
+    have['tornado'] = False
+else:
+    have['tornado'] = True
 
 #-----------------------------------------------------------------------------
 # Functions and classes
 #-----------------------------------------------------------------------------
 
 def report():
     """Return a string with a summary report of test-related variables."""
 
     out = [ sys_info(), '\n']
 
     avail = []
     not_avail = []
     
     for k, is_avail in have.items():
         if is_avail:
             avail.append(k)
         else:
             not_avail.append(k)
 
     if avail:
         out.append('\nTools and libraries available at test time:\n')
         avail.sort()
         out.append('   ' + ' '.join(avail)+'\n')
 
     if not_avail:
         out.append('\nTools and libraries NOT available at test time:\n')
         not_avail.sort()
         out.append('   ' + ' '.join(not_avail)+'\n')
         
     return ''.join(out)
 
 
 def make_exclude():
     """Make patterns of modules and packages to exclude from testing.
 
     For the IPythonDoctest plugin, we need to exclude certain patterns that
     cause testing problems.  We should strive to minimize the number of
     skipped modules, since this means untested code.
 
     These modules and packages will NOT get scanned by nose at all for tests.
     """
     # Simple utility to make IPython paths more readably, we need a lot of
     # these below
     ipjoin = lambda *paths: pjoin('IPython', *paths)
     
     exclusions = [ipjoin('external'),
                   pjoin('IPython_doctest_plugin'),
                   ipjoin('quarantine'),
                   ipjoin('deathrow'),
                   ipjoin('testing', 'attic'),
                   # This guy is probably attic material
                   ipjoin('testing', 'mkdoctests'),
                   # Testing inputhook will need a lot of thought, to figure out
                   # how to have tests that don't lock up with the gui event
                   # loops in the picture
                   ipjoin('lib', 'inputhook'),
                   # Config files aren't really importable stand-alone
                   ipjoin('config', 'default'),
                   ipjoin('config', 'profile'),
                   ]
 
     if not have['wx']:
         exclusions.append(ipjoin('lib', 'inputhookwx'))
         
     # We do this unconditionally, so that the test suite doesn't import
     # gtk, changing the default encoding and masking some unicode bugs.
     exclusions.append(ipjoin('lib', 'inputhookgtk'))
 
     # These have to be skipped on win32 because the use echo, rm, cd, etc.
     # See ticket https://github.com/ipython/ipython/issues/87
     if sys.platform == 'win32':
         exclusions.append(ipjoin('testing', 'plugin', 'test_exampleip'))
         exclusions.append(ipjoin('testing', 'plugin', 'dtexample'))
 
     if not have['pexpect']:
         exclusions.extend([ipjoin('scripts', 'irunner'),
                            ipjoin('lib', 'irunner'),
                            ipjoin('lib', 'tests', 'test_irunner')])
 
     if not have['zmq']:
         exclusions.append(ipjoin('zmq'))
         exclusions.append(ipjoin('frontend', 'qt'))
         exclusions.append(ipjoin('parallel'))
     elif not have['qt']:
         exclusions.append(ipjoin('frontend', 'qt'))
     
     if not have['pymongo']:
         exclusions.append(ipjoin('parallel', 'controller', 'mongodb'))
         exclusions.append(ipjoin('parallel', 'tests', 'test_mongodb'))
 
     if not have['matplotlib']:
         exclusions.extend([ipjoin('lib', 'pylabtools'),
                            ipjoin('lib', 'tests', 'test_pylabtools')])
 
     if not have['tornado']:
         exclusions.append(ipjoin('frontend', 'html'))
 
     # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
     if sys.platform == 'win32':
         exclusions = [s.replace('\\','\\\\') for s in exclusions]
 
     return exclusions
 
 
 class IPTester(object):
     """Call that calls iptest or trial in a subprocess.
     """
     #: string, name of test runner that will be called
     runner = None
     #: list, parameters for test runner
     params = None
     #: list, arguments of system call to be made to call test runner
     call_args = None
     #: list, process ids of subprocesses we start (for cleanup)
     pids = None
     
     def __init__(self, runner='iptest', params=None):
         """Create new test runner."""
         p = os.path
         if runner == 'iptest':
             iptest_app = get_ipython_module_path('IPython.testing.iptest')
             self.runner = pycmd2argv(iptest_app) + sys.argv[1:]
         else:
             raise Exception('Not a valid test runner: %s' % repr(runner))
         if params is None:
             params = []
         if isinstance(params, str):
             params = [params]
         self.params = params
 
         # Assemble call
         self.call_args = self.runner+self.params
 
         # Store pids of anything we start to clean up on deletion, if possible
         # (on posix only, since win32 has no os.kill)
         self.pids = []
 
     if sys.platform == 'win32':
         def _run_cmd(self):
             # On Windows, use os.system instead of subprocess.call, because I
             # was having problems with subprocess and I just don't know enough
             # about win32 to debug this reliably.  Os.system may be the 'old
             # fashioned' way to do it, but it works just fine.  If someone
             # later can clean this up that's fine, as long as the tests run
             # reliably in win32.
             # What types of problems are you having. They may be related to
             # running Python in unboffered mode. BG.
             return os.system(' '.join(self.call_args))
     else:
         def _run_cmd(self):
             # print >> sys.stderr, '*** CMD:', ' '.join(self.call_args) # dbg
             subp = subprocess.Popen(self.call_args)
             self.pids.append(subp.pid)
             # If this fails, the pid will be left in self.pids and cleaned up
             # later, but if the wait call succeeds, then we can clear the
             # stored pid.
             retcode = subp.wait()
             self.pids.pop()
             return retcode
         
     def run(self):
         """Run the stored commands"""
         try:
             return self._run_cmd()
         except:
             import traceback
             traceback.print_exc()
             return 1  # signal failure
 
     def __del__(self):
         """Cleanup on exit by killing any leftover processes."""
 
         if not hasattr(os, 'kill'):
             return
         
         for pid in self.pids:
             try:
                 print 'Cleaning stale PID:', pid
                 os.kill(pid, signal.SIGKILL)
             except OSError:
                 # This is just a best effort, if we fail or the process was
                 # really gone, ignore it.
                 pass     
 
 
 def make_runners():
     """Define the top-level packages that need to be tested.
     """
 
     # Packages to be tested via nose, that only depend on the stdlib
     nose_pkg_names = ['config', 'core', 'extensions', 'frontend', 'lib',
                      'scripts', 'testing', 'utils', 'nbformat' ]
     
     if have['zmq']:
         nose_pkg_names.append('parallel')
     
     # For debugging this code, only load quick stuff
     #nose_pkg_names = ['core', 'extensions']  # dbg
 
     # Make fully qualified package names prepending 'IPython.' to our name lists
     nose_packages = ['IPython.%s' % m for m in nose_pkg_names ]
 
     # Make runners
     runners = [ (v, IPTester('iptest', params=v)) for v in nose_packages ]
     
     return runners
 
 
 def run_iptest():
     """Run the IPython test suite using nose.
     
     This function is called when this script is **not** called with the form
     `iptest all`.  It simply calls nose with appropriate command line flags
     and accepts all of the standard nose arguments.
     """
 
     warnings.filterwarnings('ignore', 
         'This will be removed soon.  Use IPython.testing.util instead')
 
     argv = sys.argv + [ '--detailed-errors',  # extra info in tracebacks
                                                 
                         # Loading ipdoctest causes problems with Twisted, but
                         # our test suite runner now separates things and runs
                         # all Twisted tests with trial.
                         '--with-ipdoctest',
                         '--ipdoctest-tests','--ipdoctest-extension=txt',
                         
                         # We add --exe because of setuptools' imbecility (it
                         # blindly does chmod +x on ALL files).  Nose does the
                         # right thing and it tries to avoid executables,
                         # setuptools unfortunately forces our hand here.  This
                         # has been discussed on the distutils list and the
                         # setuptools devs refuse to fix this problem!
                         '--exe',
                         ]
 
     if nose.__version__ >= '0.11':
         # I don't fully understand why we need this one, but depending on what
         # directory the test suite is run from, if we don't give it, 0 tests
         # get run.  Specifically, if the test suite is run from the source dir
         # with an argument (like 'iptest.py IPython.core', 0 tests are run,
         # even if the same call done in this directory works fine).  It appears
         # that if the requested package is in the current dir, nose bails early
         # by default.  Since it's otherwise harmless, leave it in by default
         # for nose >= 0.11, though unfortunately nose 0.10 doesn't support it.
         argv.append('--traverse-namespace')
 
     # use our plugin for doctesting.  It will remove the standard doctest plugin
     # if it finds it enabled
     plugins = [IPythonDoctest(make_exclude()), KnownFailure()]
     # We need a global ipython running in this process
     globalipapp.start_ipython()
     # Now nose can run
     TestProgram(argv=argv, addplugins=plugins)
 
 
 def run_iptestall():
     """Run the entire IPython test suite by calling nose and trial.
     
     This function constructs :class:`IPTester` instances for all IPython
     modules and package and then runs each of them.  This causes the modules
     and packages of IPython to be tested each in their own subprocess using
     nose or twisted.trial appropriately.
     """
 
     runners = make_runners()
 
     # Run the test runners in a temporary dir so we can nuke it when finished
     # to clean up any junk files left over by accident.  This also makes it
     # robust against being run in non-writeable directories by mistake, as the
     # temp dir will always be user-writeable.
     curdir = os.getcwdu()
     testdir = tempfile.gettempdir()
     os.chdir(testdir)
 
     # Run all test runners, tracking execution time
     failed = []
     t_start = time.time()
     try:
         for (name, runner) in runners:
             print '*'*70
             print 'IPython test group:',name
             res = runner.run()
             if res:
                 failed.append( (name, runner) )
     finally:
         os.chdir(curdir)
     t_end = time.time()
     t_tests = t_end - t_start
     nrunners = len(runners)
     nfail = len(failed)
     # summarize results
     print
     print '*'*70
     print 'Test suite completed for system with the following information:'
     print report()
     print 'Ran %s test groups in %.3fs' % (nrunners, t_tests)
     print
     print 'Status:'
     if not failed:
         print 'OK'
     else:
         # If anything went wrong, point out what command to rerun manually to
         # see the actual errors and individual summary
         print 'ERROR - %s out of %s test groups failed.' % (nfail, nrunners)
         for name, failed_runner in failed:
             print '-'*40
             print 'Runner failed:',name
             print 'You may wish to rerun this one individually, with:'
             print ' '.join(failed_runner.call_args)
             print
         # Ensure that our exit code indicates failure
         sys.exit(1)
 
 
 def main():
     for arg in sys.argv[1:]:
         if arg.startswith('IPython'):
             # This is in-process
             run_iptest()
     else:
         # This starts subprocesses
         run_iptestall()
 
 
 if __name__ == '__main__':
     main()

docs/source/install/install.txt

@@ -1,403 +1,401 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.6 or 2.7.  There
 is an experimental port of IPython for Python3 `on GitHub 
 <https://github.com/ipython/ipython-py3k>`_
 
 .. warning::
 
     Officially, IPython supports Python versions 2.6 and 2.7.
 
     IPython 0.11 has a hard syntax dependency on 2.6, and will no longer work
     on Python <= 2.5.
 
 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.
 
 .. note::
 
     On Windows, IPython *does* depend on :mod:`setuptools`, and it is recommended
     that you install the :mod:`distribute` package, which improves
     :mod:`setuptools` and fixes various bugs.
     
     We hope to remove this dependency in 0.12.
 
 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:
 
 .. code-block:: bash
 
     $ easy_install ipython[zmq,test]
 
 This will get pyzmq, which is 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:
 
 .. code-block:: bash
 
     $ 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.  If you install IPython with :mod:`setuptools`, (e.g. with `easy_install`),
 then the appropriate :mod:`readline` for your platform will be installed.
 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`:
 
 .. 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
 <https://github.com/ipython/ipython/downloads>`_.  Then do the following:
 
 .. code-block:: bash
 
     $ 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
 -------
 
 .. note::
 
     On Windows, IPython requires :mod:`setuptools` or :mod:`distribute`.
     
     We hope to remove this dependency in 0.12.
 
 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
    `here <http://ipython.scipy.org/dist/>`_
 
 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
    install``).
 
 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
 
 Note for Windows 64 bit users: you may have difficulties with the stock
 installer on 64 bit systems; in this case (since we currently do not have 64
 bit builds of the Windows installer) your best bet is to install from source
 with the setuptools method indicated in #3 above.  See `this bug report`_ for
 further details.
 
 .. _this bug report: https://bugs.launchpad.net/ipython/+bug/382214
 
    
 Installing the development version
 ----------------------------------
 
 It is also possible to install the development version of IPython from our
 `Git <http://git-scm.com/>`_ source code repository.  To do this you will
 need to have Git installed on your system.  Then just do:
 
 .. code-block:: bash
 
     $ git clone https://github.com/ipython/ipython.git
     $ 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:
 
 .. code-block:: bash
 
     $ 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:
 
 .. code-block:: bash
 
     $ git 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.
 
 When IPython is installed with :mod:`setuptools`, (e.g. with `easy_install`),
 readline is added as a dependency on OS X, and PyReadline on Windows, and will
 be installed on your system.  However, if you do not use setuptools, you may
 have to install one of these packages yourself.
 
 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 seem
 to have been resolved.  While you may find libedit sufficient, we have
 occasional reports of bugs with it and several developers who use OS X as their
 main environment consider libedit unacceptable for productive, regular use with
 IPython.
 
 Therefore, we *strongly* recommend that on OS X you get the full
 :mod:`readline` module.  We will *not* consider completion/history problems to
 be bugs for IPython if you are using libedit.
 
 To get a working :mod:`readline` module, just do (with :mod:`setuptools`
 installed):
 
 .. 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 likely 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 <https://launchpad.net/pyreadline/+download>`_.
 
 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`:
 
 .. code-block:: bash
 
     $ easy_install nose
 
 Another way of getting this is to do:
 
 .. 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:
 
 .. code-block:: bash
 
     $ iptest
 
 pexpect
 -------
 
 The pexpect_ package is used in IPython's :command:`irunner` script, as well as
 for managing subprocesses. IPython now includes a version of pexpect in
 :mod:`IPython.external`, but if you have installed pexpect, IPython will use
 that instead. On Unix platforms (including OS X), just do:
 
 .. code-block:: bash
 
     $ easy_install pexpect
 
 Windows users are out of luck as pexpect does not run there.
 
 Dependencies for IPython.parallel (parallel computing)
 ======================================================
 
 :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`, 
 which uses ZeroMQ for all communication.
 
 IPython.parallel provides a nice architecture for parallel computing.  The
 main focus of this architecture is on interactive parallel computing.  These
 features require just one package: PyZMQ.  See the next section for PyZMQ
 details.
 
 On a Unix style platform (including OS X), if you want to use
 :mod:`setuptools`, you can just do:
 
 .. code-block:: bash
 
     $ easy_install ipython[zmq]    # will include pyzmq
 
 Security in IPython.parallel is provided by SSH tunnels.  By default, Linux
 and OSX clients will use the shell ssh command, but on Windows, we also
 support tunneling with paramiko_.
 
 Dependencies for IPython.zmq
 ============================
 
 pyzmq
 -----
 
 IPython 0.11 introduced some new functionality, including a two-process
 execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
 are found in the PyZMQ_ project, which is easy_install-able once you have
 ZeroMQ installed.  If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows,
 pyzmq has eggs that include ZeroMQ itself.
 
 IPython.zmq depends on pyzmq >= 2.1.4.
 
 Dependencies for the IPython QT console
 =======================================
 
 pyzmq
 -----
 
 Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
 PyZMQ.
 
 Qt
 --
 
 Also with 0.11, a new GUI was added using the work in :mod:`IPython.zmq`, which
 can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
 with either PyQt, which can be installed from the `PyQt website
 <http://www.riverbankcomputing.co.uk/>`_, or `PySide
 <http://www.pyside.org/>`_, from Nokia.
 
 pygments
 --------
 
 The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
 project, which is easy_install-able.
 
+.. _installnotebook:
 
 Dependencies for the IPython HTML notebook
 ==========================================
 
 The IPython notebook is a notebook-style web interface to IPython and can be
 started withe command ``ipython notebook``.
 
 pyzmq
 -----
 
 Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console` packages, 
 the HTML notebook requires ZeroMQ and PyZMQ.
 
 Tornado
 -------
 
-The IPython notebook uses the Tornado_ project for its HTTP server.  As of this
-writing, we require a development version from github, as version 2.0 is *not
-sufficient*.  You can either clone their git repository yourself and install it
-manually, or install directly from github with::
+The IPython notebook uses the Tornado_ project for its HTTP server.  Tornado 2.1
+is required, in order to support current versions of browsers, due to an update
+to the websocket protocol.
 
-    easy_install https://github.com/facebook/tornado/tarball/master
 
-    
 MathJax
 -------
 
 The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
 in web browsers. Because MathJax is large, we don't include it with
 IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
 network connection, or want to use LaTeX without an internet connection at all,
 we do include a utility to aid in downloading MathJax and installing it into
 the proper location::
 
     from IPython.external.mathjax import install_mathjax
     install_mathjax()
 
 This function does require write access to the IPython install directory, so if you
 have a system-wide Python install, it may need to be done from a ``sudo python`` session.
 
 Browser Compatibility
 ---------------------
 
 The notebook uses WebSockets and the flexible box model. These features are
 available in the following browsers:
 
 * Chrome.
 * Safari.
 * Firefox 4 and 5. These browsers have WebSocket support, but it is disabled by
   default. You can enable it by entering ``about:config`` in the URL bar and then
   setting ``network.websocket.enabled`` and ``network.websocket.override-security-block``
   to ``true``.
 * Firefox 6. Starting with version 6, Firefox has WebSocket support enabled by default.
 
 Internet Explorer 9 does not support WebSockets or the flexible box model, but
 these features should appear in Internet Explorer 10.
 
 
 .. _ZeroMQ: http://www.zeromq.org
 .. _PyZMQ: https://github.com/zeromq/pyzmq
 .. _paramiko: https://github.com/robey/paramiko
 .. _pygments: http://pygments.org
 .. _pexpect: http://www.noah.org/wiki/Pexpect
 .. _Tornado: http://www.tornadoweb.org
 .. _MathJax: http://www.mathjax.org

docs/source/interactive/htmlnotebook.txt

@@ -1,213 +1,217 b''
 .. _htmlnotebook:
 
 =========================
 An HTML Notebook IPython
 =========================
 
+.. seealso::
+
+    :ref:`Installation requirements <installnotebook>` for the Notebook.
+
 The IPython Notebook consists of two related components:
 
 * An JSON based Notebook document format for recording and distributing
   Python code and rich text.
 * A web-based user interface for authoring and running notebook documents.
 
 The Notebook can be used by starting the Notebook server with the 
 command::
 
     $ ipython notebook
 
 Note that by default, the notebook doesn't load pylab, it's just a normal
 IPython session like any other.  If you want pylab support, you must use::
     
     $ ipython notebook --pylab
 
 which will behave similar to the terminal and Qt console versions, using your
 default matplotlib backend and providing floating interactive plot windows.  If
 you want inline figures, you must manually select the ``inline`` backend::
 
     $ ipython notebook --pylab=inline
 
 You can start the notebook to communicate via a secure protocol mode using a
 self-signed certificate by typing::
 
     $ ipython notebook --certfile=mycert.pem
 
 .. note::
 
     A self-signed certificate can be generated with openssl. For example:
 
     openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
 
 This server uses the same ZeroMQ-based two process kernel architecture as
 the QT Console as well Tornado for serving HTTP/S requests. Some of the main
 features of the Notebook include:
 
 * Display rich data (png/html/latex/svg) in the browser as a result of
   computations.
 * Compose text cells using HTML and Markdown.
 * Import and export notebook documents in range of formats (.ipynb, .py).
 * In browser syntax highlighting, tab completion and autoindentation.
 * Inline matplotlib plots that can be stored in Notebook documents and opened
   later.
 
 See :ref:`our installation documentation <install_index>` for directions on
 how to install the notebook and its dependencies.
 
 .. note::
 
    You can start more than one notebook server at the same time, if you want to
    work on notebooks in different directories.  By default the first notebook
    server starts in port 8888, later notebooks search for random ports near
    that one.  You can also manually specify the port with the ``--port``
    option.
    
 
 Basic Usage
 ===========
 
 The landing page of the notebook server application, which we call the IPython
 Notebook *dashboard*, shows the notebooks currently available in the directory
 in which the application was started, and allows you to create new notebooks.
 
 A notebook is a combination of two things:
 
 1. An interactive session connected to an IPython kernel, controlled by a web
 application that can send input to the console and display many types of output
 (text, graphics, mathematics and more).  This is the same kernel used by the
 :ref:`Qt console <qtconsole>`, but in this case the web console sends input in
 persistent cells that you can edit in-place instead of the vertically scrolling
 terminal style used by the Qt console.
 
 2. A document that can save the inputs and outputs of the session as well as
 additional text that accompanies the code but is not meant for execution.  In
 this way, notebook files serve as a complete computational record of a session
 including explanatory text and mathematics, code and resulting figures.  These
 documents are internally JSON files and are saved with the ``.ipynb``
 extension.
 
 If you have ever used the Mathematica or Sage notebooks (the latter is also
 web-based__) you should feel right at home.  If you have not, you should be
 able to learn how to use it in just a few minutes.
 
 .. __: http://sagenb.org
 
 
 Creating and editing notebooks
 ------------------------------
 
 You can create new notebooks from the dashboard with the ``New Notebook``
 button or open existing ones by clicking on their name.  Once in a notebook,
 your browser tab will reflect the name of that notebook (prefixed with "IPy:").
 The URL for that notebook is not meant to be human-readable and is *not*
 persistent across invocations of the notebook server.
 
 You can also drag and drop into the area listing files any python file: it
 will be imported into a notebook with the same name (but ``.ipynb`` extension)
 located in the directory where the notebook server was started.  This notebook
 will consist of a single cell with all the code in the file, which you can
 later manually partition into individual cells for gradual execution, add text
 and graphics, etc.
 
 Workflow and limitations
 ------------------------
 
 The normal workflow in a notebook is quite similar to a normal IPython session,
 with the difference that you can edit a cell in-place multiple times until you
 obtain the desired results rather than having to rerun separate scripts with
 the ``%run`` magic (though magics also work in the notebook).   Typically
 you'll work on a problem in pieces, organizing related pieces into cells and
 moving forward as previous parts work correctly.  This is much more convenient
 for interactive exploration than breaking up a computation into scripts that
 must be executed together, especially if parts of them take a long time to run
 (you can use tricks with namespaces and ``%run -i``, but we think the notebook
 is a more natural solution for  that kind of problem).
 
 The only significant limitation the notebook currently has, compared to the qt
 console, is that it can not run any code that expects input from the kernel
 (such as scripts that call :func:`raw_input`).  Very importantly, this means
 that the ``%debug`` magic does *not* work in the notebook!  We intend to
 correct this limitation, but in the meantime, there is a way to debug problems
 in the notebook: you can attach a Qt console to your existing notebook kernel,
 and run ``%debug`` from the Qt console.  Simply look for the lines in the
 terminal where you started the kernel that read something like::
 
     [IPKernelApp] To connect another client to this kernel, use:
     [IPKernelApp] --existing --shell=53328 --iopub=53817 --stdin=34736 --hb=45543
 
 and then start a qt console pointing to that kernel::
 
     ipython qtconsole --existing --shell=53328 --iopub=53817 --stdin=34736 --hb=45543
 
     
 Text input
 ----------
 
 In addition to code cells and the output they procude (such as figures), you
 can also type text not meant for execution.  To type text, change the type of a
 cell from ``Code`` to ``Markdown`` by using the button or the :kbd:`Ctrl-m m`
 keybinding (see below).  You can then type any text in Markdown_ syntax, as
 well as mathematical expressions if you use ``$...$`` for inline math or
 ``$$...$$`` for displayed math.
 
 Exporting a notebook
 --------------------
 
 If you want to provide others with a static HTML or PDF view of your notebook,
 use the ``Print`` button.  This opens a static view of the document, which you
 can print to PDF using your operating system's facilities, or save to a file
 with your web browser's 'Save' option (note that typically, this will create
 both an html file *and* a directory called `notebook_name_files` next to it
 that contains all the necessary style information, so if you intend to share
 this, you must send the directory along with the main html file).
 
 The `Download` button lets you save a notebook file to the Download area
 configured by your web browser (particularly useful if you are running the
 notebook server on a remote host and need a file locally).  The notebook is
 saved by default with the ``.ipynb`` extension and the files contain JSON data
 that is not meant for human editing or consumption.  But you can always export
 the input part of a notebook to a plain python script by choosing Python format
 in the `Download` drop list.  This removes all output and saves the text cells
 in comment areas.
 
 .. warning::
 
    While in simple cases you can roundtrip a notebook to Python, edit the
    python file and import it back without loss, this is in general *not
    guaranteed to work at all*.  As the notebook format evolves in complexity,
    there will be attributes of the notebook that will not survive a roundtrip
    through the Python form.  You should think of the Python format as a way to
    output a script version of a notebook and the import capabilities as a way
    to load existing code to get a notebook started.  But the Python version is
    *not* an alternate notebook format.
 
     
 Keyboard use
 ------------
 
 All actions in the notebook can be achieved with the mouse, but we have also
 added keyboard shortcuts for the most common ones, so that productive use of
 the notebook can be achieved with minimal mouse intervention.  The main
 key bindings you need to remember are:
 
 * :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console),
   show output (if any) and create a new cell below.  Note that in the notebook,
   simply using :kbd:`Enter` *never* forces execution, it simply inserts a new
   line in the current cell.  Therefore, in the notebook you must always use
   :kbd:`Shift-Enter` to get execution (or use the mouse and click on the ``Run
   Selected`` button).
 
 * :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any
   output is shown but the cursor cursor stays in the current cell, whose input
   area is flushed empty.  This is convenient to do quick in-place experiments
   or query things like filesystem content without creating additional cells you
   may not want saved in your notebook.
 
 * :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist
   of an additional single letter.  Type :kbd:`Ctrl-m h` (that is, the sole
   letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining
   available keybindings.
 
 
 Notebook document format
 ========================