Update various references to IPython's homepage.

IPython/core/release.py

@@ -1,123 +1,123 b''
 # -*- coding: utf-8 -*-
 """Release data for the IPython project."""
 
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2008-2010, IPython Development Team.
 #  Copyright (c) 2001-2007, Fernando Perez <[e-mail]>
 #  Copyright (c) 2001, Janko Hauser <[e-mail]>
 #  Copyright (c) 2001, Nathaniel Gray <[e-mail]>
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 # Name of the package for release purposes.  This is the name which labels
 # the tarballs and RPMs made by distutils, so it's best to lowercase it.
 name = 'ipython'
 
 # IPython version information.  An empty _version_extra corresponds to a full
 # release.  'dev' as a _version_extra string means this is a development
 # version
 _version_major = 0
 _version_minor = 11
 _version_micro = ''  # use '' for first of series, number for 1 and above
 _version_extra = 'dev'
 #_version_extra = ''  # Uncomment this for full releases
 
 # Construct full version string from these.
 _ver = [_version_major, _version_minor]
 if _version_micro:
     _ver.append(_version_micro)
 if _version_extra:
     _ver.append(_version_extra)
 
 __version__ = '.'.join(map(str, _ver))
 
 version = __version__  # backwards compatibility name
 
 description = "An interactive computing environment for Python"
 
 long_description = \
 """
 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.
 
 The enhanced interactive Python shell has the following main features:
 
 * Comprehensive object introspection.
 
 * Input history, persistent across sessions.
 
 * Caching of output results during a session with automatically generated
   references.
 
 * Readline based name completion.
 
 * Extensible system of 'magic' commands for controlling the environment and
   performing many tasks related either to IPython or the operating system.
 
 * Configuration system with easy switching between different setups (simpler
   than changing $PYTHONSTARTUP environment variables every time).
 
 * Session logging and reloading.
 
 * Extensible syntax processing for special purpose situations.
 
 * Access to the system shell with user-extensible alias system.
 
 * Easily embeddable in other Python programs and wxPython GUIs.
 
 * Integrated access to the pdb debugger and the Python profiler. 
 
 The parallel computing architecture has the following main features:
 
 * 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.
 
 * Both blocking and fully asynchronous interfaces.
 
 * High level APIs that enable many things to be parallelized in a few lines
   of code.
 
 * Share live parallel jobs with other users securely.  
 
 * Dynamically load balanced task farming system.
 
 * Robust error handling in parallel code.
 
 The latest development version is always available from IPython's `GitHub
 site <http://github.com/ipython>`_.
 """
 
 license = 'BSD'
 
 authors = {'Fernando' : ('Fernando Perez','[e-mail]'),
            'Janko'    : ('Janko Hauser','[e-mail]'),
            'Nathan'   : ('Nathaniel Gray','[e-mail]'),
            'Ville'    : ('Ville Vainio','[e-mail]'),
            'Brian'    : ('Brian E Granger', '[e-mail]'),
            'Min'      : ('Min Ragan-Kelley', '[e-mail]')
            }
 
 author = 'The IPython Development Team'
 
 author_email = '[e-mail]'
 
-url = 'http://ipython.scipy.org'
+url = 'http://ipython.org'
 
 download_url = 'http://ipython.scipy.org/dist'
 
 platforms = ['Linux','Mac OSX','Windows XP/2000/NT','Windows 95/98/ME']
 
 keywords = ['Interactive','Interpreter','Shell','Parallel','Distributed']

IPython/core/usage.py

@@ -1,509 +1,509 b''
 # -*- coding: utf-8 -*-
 """Usage information for the main IPython applications.
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #  Copyright (C) 2001-2007 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 import sys
 from IPython.core import release
 
 cl_usage = """\
 ipython [options] [files]
 
 IPython: an enhanced interactive Python shell.
 
     A Python shell with automatic history (input and output), dynamic object
     introspection, easier configuration, command completion, access to the
     system shell and more.  IPython can also be embedded in running programs.
 
     If invoked with no options, it executes all the files listed in sequence
     and exits, use -i to enter interactive mode after running the files.  Files
     ending in .py will be treated as normal Python, but files ending in .ipy
     can contain special IPython syntax (magic commands, shell expansions, etc.)
 
     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
     ipython_config.py configuration file for details on those.
 
     This file is typically installed in the IPYTHON_DIR directory. For Linux
     users, this will be $HOME/.config/ipython, and for other users it will be
     $HOME/.ipython.  For Windows users, $HOME resolves to C:\\Documents and
     Settings\\YourUserName in most instances.
 
     In IPython's documentation, we will refer to this directory as IPYTHON_DIR,
     you can change its default location by setting any path you want in this
     environment variable.
 
     For more information, see the manual available in HTML and PDF in your
-    installation, or online at http://ipython.scipy.org.
+    installation, or online at http://ipython.org/documentation.html.
 """
 
 interactive_usage = """
 IPython -- An enhanced Interactive Python
 =========================================
 
 IPython offers a combination of convenient shell features, special commands
 and a history mechanism for both input (command history) and output (results
 caching, similar to Mathematica). It is intended to be a fully compatible
 replacement for the standard Python interpreter, while offering vastly
 improved functionality and flexibility.
 
 At your system command line, type 'ipython -help' to see the command line
 options available. This document only describes interactive features.
 
 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.
 
 MAIN FEATURES
 
 * 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.
 
 * Magic commands: type %magic for information on the magic subsystem.
 
 * System command aliases, via the %alias command or the ipythonrc config file.
 
 * 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.
 
   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, printed otherwise.
 
   The ?/?? system gives access to the full source code for any object (if
   available), shows function prototypes and other useful information.
 
   If you just want to see an object's docstring, type '%pdoc object' (without
   quotes, and without % if you have automagic on).
 
   Both %pdoc and ?/?? give you access to documentation even on things which are
   not explicitely defined. Try for example typing {}.get? or after import os,
   type os.path.abspath??. The magic functions %pdef, %source and %file operate
   similarly.
 
 * Completion in the local namespace, by typing TAB at the prompt.
 
   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.
 
   This feature requires the readline and rlcomplete modules, so it won't work
   if your Python lacks readline support (such as under Windows).
 
 * Search previous command history in two ways (also requires readline):
 
   - 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.
 
   - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
   your history for lines that match what you've typed so far, completing as
   much as it can.
 
 * Persistent command history across sessions (readline required).
 
 * Logging of input with the ability to save and restore a working session.
   
 * System escape with !. Typing !ls will run 'ls' in the current directory.
 
 * The reload command does a 'deep' 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. See the magic xmode and
   xcolor functions for details (just type %magic).
 
 * Input caching system:
 
   IPython offers numbered prompts (In/Out) with input and output caching. All
   input is saved and can be retrieved as variables (besides the usual arrow
   key recall).
 
   The following GLOBAL variables always exist (so don't overwrite them!):
   _i: stores previous input.
   _ii: next previous.
   _iii: next-next previous.
   _ih : a list of all input _ih[n] is the input from line n.
 
   Additionally, global variables named _i<n> are dynamically created (<n>
   being the prompt counter), such that _i<n> == _ih[<n>]
 
   For example, what you typed at prompt 14 is available as _i14 and _ih[14].
 
   You can create macros which contain multiple input lines from this history,
   for later re-execution, with the %macro function.
 
   The history function %hist allows you to see any part of your input history
   by printing a range of the _i variables. Note that inputs which contain
   magic functions (%) appear in the history with a prepended comment. This is
   because they aren't really valid Python code, so you can't exec them.
 
 * 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!):
   _ (one underscore): previous output.
   __ (two underscores): next previous.
   ___ (three underscores): next-next previous.
 
   Global variables named _<n> are dynamically created (<n> being the prompt
   counter), such that the result of output <n> is always available as _<n>.
 
   Finally, a global dictionary named _oh exists with entries for all lines
   which generated output.
 
 * 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.
 
 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
 
     1. Auto-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 auto-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) 
 
     2. Auto-Quoting
         You can force auto-quoting of a function's arguments by using ',' 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 ',' MUST be the first character on the line!  This
         won't work:
             >>> x = ,my_function /home/me    # syntax error
 """
 
 interactive_usage_min =  """\
 An enhanced console for Python.
 Some of its features are:
 - Readline support if the readline library is present.
 - Tab completion in the local namespace.
 - Logging of input, see command-line options.
 - System shell escape via ! , eg !ls.
 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
 - Keeps track of locally defined variables via %who, %whos.
 - Show object information with a ? eg ?x or x? (use ?? for more info).
 """
 
 quick_reference = r"""
 IPython -- An enhanced Interactive Python - Quick Reference Card
 ================================================================
 
 obj?, obj??      : Get help, or more help for object (also works as
                    ?obj, ??obj).
 ?foo.*abc*       : List names in 'foo' containing 'abc' in them.
 %magic           : Information about IPython's 'magic' % functions.
 
 Magic functions are prefixed by %, and typically take their arguments without
 parentheses, quotes or even commas for convenience.
  
 Example magic function calls:
 
 %alias d ls -F   : 'd' is now an alias for 'ls -F'
 alias d ls -F    : Works if 'alias' not a python name
 alist = %alias   : Get list of aliases to 'alist'
 cd /usr/share    : Obvious. cd -<tab> to choose from visited dirs.
 %cd??            : See help AND source for magic %cd
 
 System commands:
     
 !cp a.txt b/     : System command escape, calls os.system()
 cp a.txt b/      : after %rehashx, most system commands work without !
 cp ${f}.txt $bar : Variable expansion in magics and system commands
 files = !ls /usr : Capture sytem command output
 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
 
 History:
 
 _i, _ii, _iii    : Previous, next previous, next next previous input
 _i4, _ih[2:5]    : Input history line 4, lines 2-4
 exec _i81        : Execute input history line #81 again
 %rep 81          : Edit input history line #81        
 _, __, ___       : previous, next previous, next next previous output
 _dh              : Directory history
 _oh              : Output history
 %hist            : Command history. '%hist -g foo' search history for 'foo'
 
 Autocall:
 
 f 1,2            : f(1,2)
 /f 1,2           : f(1,2) (forced autoparen)
 ,f 1 2           : f("1","2")
 ;f 1 2           : f("1 2")
 
 Remember: TAB completion works in many contexts, not just file names
 or python names.
 
 The following magic functions are currently available:
 
 """
 
 gui_reference = """\
 ===============================
  The graphical IPython console
 ===============================
 
 This console is designed to emulate the look, feel and workflow of a terminal
 environment, while adding a number of enhancements that are simply not possible
 in a real terminal, such as inline syntax highlighting, true multiline editing,
 inline graphics and much more.
 
 This quick reference document contains the basic information you'll need to
 know to make the most efficient use of it.  For the various command line
 options available at startup, type ``--help`` at the command line.
 
 
 Multiline editing
 =================
 
 The graphical console is capable of true multiline editing, but it also tries
 to behave intuitively like a terminal when possible.  If you are used to
 IPyhton's old terminal behavior, you should find the transition painless, and
 once you learn a few basic keybindings it will be a much more efficient
 environment.
 
 For single expressions or indented blocks, the console behaves almost like the
 terminal IPython: single expressions are immediately evaluated, and indented
 blocks are evaluated once a single blank line is entered::
 
     In [1]: print "Hello IPython!"  # Enter was pressed at the end of the line
     Hello IPython!
     
     In [2]: for i in range(10):
        ...: 	print i,
        ...: 	
     0 1 2 3 4 5 6 7 8 9
 
 If you want to enter more than one expression in a single input block
 (something not possible in the terminal), you can use ``Control-Enter`` at the
 end of your first line instead of ``Enter``.  At that point the console goes
 into 'cell mode' and even if your inputs are not indented, it will continue
 accepting arbitrarily many lines until either you enter an extra blank line or
 you hit ``Shift-Enter`` (the key binding that forces execution).  When a
 multiline cell is entered, IPython analyzes it and executes its code producing
 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
 cell is executed as if it was a script.  An example should clarify this::
 
     In [3]: x=1  # Hit C-Enter here
        ...: y=2  # from now on, regular Enter is sufficient
        ...: z=3
        ...: x**2  # This does *not* produce an Out[] value
        ...: x+y+z  # Only the last expression does
        ...: 
     Out[3]: 6
 
 The behavior where an extra blank line forces execution is only active if you
 are actually typing at the keyboard each line, and is meant to make it mimic
 the IPython terminal behavior.  If you paste a long chunk of input (for example
 a long script copied form an editor or web browser), it can contain arbitrarily
 many intermediate blank lines and they won't cause any problems.  As always,
 you can then make it execute by appending a blank line *at the end* or hitting
 ``Shift-Enter`` anywhere within the cell.
 
 With the up arrow key, you can retrieve previous blocks of input that contain
 multiple lines.  You can move inside of a multiline cell like you would in any
 text editor.  When you want it executed, the simplest thing to do is to hit the
 force execution key, ``Shift-Enter`` (though you can also navigate to the end
 and append a blank line by using ``Enter`` twice).
 
 If you've edited a multiline cell and accidentally navigate out of it with the
 up or down arrow keys, IPython will clear the cell and replace it with the
 contents of the one above or below that you navigated to.  If this was an
 accident and you want to retrieve the cell you were editing, use the Undo
 keybinding, ``Control-z``.
 
 
 Key bindings
 ============
 
 The IPython console supports most of the basic Emacs line-oriented keybindings,
 in addition to some of its own.
 
 The keybinding prefixes mean:
 
 - ``C``: Control
 - ``S``: Shift
 - ``M``: Meta (typically the Alt key)
 
 The keybindings themselves are:
 
 - ``Enter``: insert new line (may cause execution, see above).
 - ``C-Enter``: force new line, *never* causes execution.
 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
 - ``C-v``: paste text from clipboard.
 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
 - ``C-S-z``: redo.
 - ``C-o``: move to 'other' area, between pager and terminal.
 - ``C-l``: clear terminal.
 - ``C-a``: go to beginning of line.
 - ``C-e``: go to end of line.
 - ``C-k``: kill from cursor to the end of the line.
 - ``C-y``: yank (paste)
 - ``C-p``: previous line (like up arrow)
 - ``C-n``: next line (like down arrow)
 - ``C-f``: forward (like right arrow)
 - ``C-b``: back (like left arrow)
 - ``C-d``: delete next character.
 - ``M-<``: move to the beginning of the input region.
 - ``M->``: move to the end of the input region.
 - ``M-d``: delete next word.
 - ``M-Backspace``: delete previous word.
 - ``C-.``: force a kernel restart (a confirmation dialog appears).
 - ``C-+``: increase font size.
 - ``C--``: decrease font size.
 
 The IPython pager
 =================
 
 IPython will show long blocks of text from many sources using a builtin pager.
 You can control where this pager appears with the ``--paging`` command-line
 flag:
 
 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
   must quit the pager to get back to the terminal (similar to how a pager such
   as ``less`` or ``more`` works).
 
 - ``vsplit``: the console is made double-tall, and the pager appears on the
   bottom area when needed.  You can view its contents while using the terminal.
 
 - ``hsplit``: the console is made double-wide, and the pager appears on the
   right area when needed.  You can view its contents while using the terminal.
 
 - ``none``: the console never pages output.
 
 If you use the vertical or horizontal paging modes, you can navigate between
 terminal and pager as follows:
 
 - Tab key: goes from pager to terminal (but not the other way around).
 - Control-o: goes from one to another always.
 - Mouse: click on either.
 
 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
 focus on the pager area).
 
 Running subprocesses
 ====================
 
 The graphical IPython console uses the ``pexpect`` module to run subprocesses
 when you type ``!command``.  This has a number of advantages (true asynchronous
 output from subprocesses as well as very robust termination of rogue
 subprocesses with ``Control-C``), as well as some limitations.  The main
 limitation is that you can *not* interact back with the subprocess, so anything
 that invokes a pager or expects you to type input into it will block and hang
 (you can kill it with ``Control-C``).
 
 We have provided as magics ``%less`` to page files (aliased to ``%more``),
 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX.  These cover the
 most common commands you'd want to call in your subshell and that would cause
 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
 
 Display
 =======
 
 The IPython console can now display objects in a variety of formats, including
 HTML, PNG and SVG. This is accomplished using the display functions in
 ``IPython.core.display``::
 
     In [4]: from IPython.core.display import display, display_html
 
     In [5]: from IPython.core.display import display_png, display_svg
 
 Python objects can simply be passed to these functions and the appropriate
 representations will be displayed in the console as long as the objects know
 how to compute those representations. The easiest way of teaching objects how
 to format themselves in various representations is to define special methods
 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
 can also be given custom formatter functions for various types::
 
     In [6]: ip = get_ipython()
 
     In [7]: html_formatter = ip.display_formatter.formatters['text/html']
 
     In [8]: html_formatter.for_type(Foo, foo_to_html)
 
 For further details, see ``IPython.core.formatters``.
 
 Inline matplotlib graphics
 ==========================
 
 The IPython console is capable of displaying matplotlib figures inline, in SVG
 format.  If started with the ``--pylab inline`` flag, then all figures are
 rendered inline automatically.  If started with ``--pylab`` or ``--pylab <your
 backend>``, then a GUI backend will be used, but IPython's ``display()`` and
 ``getfigs()`` functions can be used to view plots inline::
 
     In [9]: display(*getfigs())    # display all figures inline
 
     In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
 """
 
 
 quick_guide = """\
 ?         -> Introduction and overview of IPython's features.
 %quickref -> Quick reference.
 help      -> Python's own help system.
 object?   -> Details about 'object', use 'object??' for extra details.
 """
 
 gui_note = """\
 %guiref   -> A brief reference about the graphical user interface.
 """
 
 default_banner_parts = [
     'Python %s\n' % (sys.version.split('\n')[0],),
     'Type "copyright", "credits" or "license" for more information.\n\n',
     'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
     quick_guide
 ]
 
 default_gui_banner_parts = default_banner_parts + [gui_note]
 
 default_banner = ''.join(default_banner_parts)
 
 default_gui_banner = ''.join(default_gui_banner_parts)

docs/emacs/ipython.el

@@ -1,492 +1,492 b''
 ;;; ipython.el --- Adds support for IPython to python-mode.el
 
 ;; Copyright (C) 2002, 2003, 2004, 2005 Alexander Schmolck
 ;; Author:        Alexander Schmolck
 ;; Keywords:      ipython python languages oop
-;; URL:           http://ipython.scipy.org
+;; URL:           http://ipython.org
 ;; Compatibility: Emacs21, XEmacs21
 ;; FIXME: #$@! INPUT RING
 (defconst ipython-version "0.11"
   "Tied to IPython main version number.")
 
 ;;; Commentary
 ;; This library makes all the functionality python-mode has when running with
 ;; the normal python-interpreter available for ipython, too. It also enables a
 ;; persistent py-shell command history across sessions (if you exit python
 ;; with C-d in py-shell) and defines the command `ipython-to-doctest', which
 ;; can be used to convert bits of a ipython session into something that can be
 ;; used for doctests. To install, put this file somewhere in your emacs
 ;; `load-path' [1] and add the following line to your ~/.emacs file (the first
 ;; line only needed if the default (``"ipython"``) is wrong)::
 ;;
 ;;   (setq ipython-command "/SOME-PATH/ipython")
 ;;   (require 'ipython)
 ;;
 ;; Ipython will be set as the default python shell, but only if the ipython
 ;; executable is in the path. For ipython sessions autocompletion with <tab>
 ;; is also enabled (experimental feature!). Please also note that all the
 ;; terminal functions in py-shell are handled by emacs's comint, **not** by
 ;; (i)python, so importing readline etc. will have 0 effect.
 ;;
 ;; To start an interactive ipython session run `py-shell' with ``M-x py-shell``
 ;; (or the default keybinding ``C-c C-!``).
 ;;
 ;; You can customize the arguments passed to the IPython instance at startup by
 ;; setting the ``py-python-command-args`` variable.  For example, to start
 ;; always in ``pylab`` mode with hardcoded light-background colors, you can
 ;; use::
 ;;
 ;; (setq py-python-command-args '("-pylab" "--colors" "LightBG"))
 ;;
 ;;
 ;; NOTE: This mode is currently somewhat alpha and although I hope that it
 ;; will work fine for most cases, doing certain things (like the
 ;; autocompletion and a decent scheme to switch between python interpreters)
 ;; properly will also require changes to ipython that will likely have to wait
 ;; for a larger rewrite scheduled some time in the future.
 ;;
 ;;
 ;; Further note that I don't know whether this runs under windows or not and
 ;; that if it doesn't I can't really help much, not being afflicted myself.
 ;;
 ;;
 ;; Hints for effective usage
 ;; -------------------------
 ;;
 ;; - IMO the best feature by far of the ipython/emacs combo is how much easier
 ;;   it makes it to find and fix bugs thanks to the ``%pdb on or %debug``/
 ;;   pdbtrack combo. Try it: first in the ipython to shell do ``%pdb on`` then
 ;;   do something that will raise an exception (FIXME nice example), or type
 ;;   ``%debug`` after the exception has been raised.  YOu'll be amazed at how
 ;;   easy it is to inspect the live objects in each stack frames and to jump to
 ;;   the corresponding sourcecode locations as you walk up and down the stack
 ;;   trace (even without ``%pdb on`` you can always use ``C-c -``
 ;;   (`py-up-exception') to jump to the corresponding source code locations).
 ;;
 ;; - emacs gives you much more powerful commandline editing and output searching
 ;;   capabilities than ipython-standalone -- isearch is your friend if you
 ;;   quickly want to print 'DEBUG ...' to stdout out etc.
 ;;
 ;; - This is not really specific to ipython, but for more convenient history
 ;;   access you might want to add something like the following to *the beggining*
 ;;   of your ``.emacs`` (if you want behavior that's more similar to stand-alone
 ;;   ipython, you can change ``meta p`` etc. for ``control p``)::
 ;;
 ;;         (require 'comint)
 ;;         (define-key comint-mode-map [(meta p)]
 ;;           'comint-previous-matching-input-from-input)
 ;;         (define-key comint-mode-map [(meta n)]
 ;;           'comint-next-matching-input-from-input)
 ;;         (define-key comint-mode-map [(control meta n)]
 ;;            'comint-next-input)
 ;;         (define-key comint-mode-map [(control meta p)]
 ;;            'comint-previous-input)
 ;;
 ;; - Be aware that if you customize py-python-command previously, this value
 ;;   will override what ipython.el does (because loading the customization
 ;;   variables comes later).
 ;;
 ;; Please send comments and feedback to the ipython-list
 ;; (<[e-mail]>) where I (a.s.) or someone else will try to
 ;; answer them (it helps if you specify your emacs version, OS etc;
 ;; familiarity with <http://www.catb.org/~esr/faqs/smart-questions.html> might
 ;; speed up things further).
 ;;
 ;; Footnotes:
 ;;
 ;;     [1] If you don't know what `load-path' is, C-h v load-path will tell
 ;;     you; if required you can also add a new directory. So assuming that
 ;;     ipython.el resides in ~/el/, put this in your emacs:
 ;;
 ;;
 ;;           (add-to-list 'load-path "~/el")
 ;;           (setq ipython-command "/some-path/ipython")
 ;;           (require 'ipython)
 ;;
 ;;
 ;;
 ;;
 ;; TODO:
 ;;      - do autocompletion properly
 ;;      - implement a proper switching between python interpreters
 ;;
 ;; BUGS:
 ;;      - neither::
 ;;
 ;;         (py-shell "-c print 'FOOBAR'")
 ;;
 ;;        nor::
 ;;
 ;;         (let ((py-python-command-args (append py-python-command-args
 ;;                                              '("-c" "print 'FOOBAR'"))))
 ;;           (py-shell))
 ;;
 ;;        seem to print anything as they should
 ;;
 ;;      - look into init priority issues with `py-python-command' (if it's set
 ;;        via custom)
 
 
 ;;; Code
 (require 'cl)
 (require 'shell)
 (require 'executable)
 (require 'ansi-color)
 
 (defcustom ipython-command "ipython"
   "*Shell command used to start ipython."
   :type 'string
   :group 'python)
 
 ;; Users can set this to nil
 (defvar py-shell-initial-switch-buffers t
   "If nil, don't switch to the *Python* buffer on the first call to
   `py-shell'.")
 
 (defvar ipython-backup-of-py-python-command nil
   "HACK")
 
 
 (defvar ipython-de-input-prompt-regexp "\\(?:
 In \\[[0-9]+\\]: *.*
 ----+> \\(.*
 \\)[\n]?\\)\\|\\(?:
 In \\[[0-9]+\\]: *\\(.*
 \\)\\)\\|^[ ]\\{3\\}[.]\\{3,\\}: *\\(.*
 \\)"
   "A regular expression to match the IPython input prompt and the python
 command after it. The first match group is for a command that is rewritten,
 the second for a 'normal' command, and the third for a multiline command.")
 (defvar ipython-de-output-prompt-regexp "^Out\\[[0-9]+\\]: "
   "A regular expression to match the output prompt of IPython.")
 
 
 (if (not (executable-find ipython-command))
     (message (format "Can't find executable %s - ipython.el *NOT* activated!!!"
                      ipython-command))
     ;; XXX load python-mode, so that we can screw around with its variables
     ;; this has the disadvantage that python-mode is loaded even if no
     ;; python-file is ever edited etc. but it means that `py-shell' works
     ;; without loading a python-file first. Obviously screwing around with
     ;; python-mode's variables like this is a mess, but well.
     (require 'python-mode)
     ;; turn on ansi colors for ipython and activate completion
     (defun ipython-shell-hook ()
       ;; the following is to synchronize dir-changes
       (make-local-variable 'shell-dirstack)
       (setq shell-dirstack nil)
       (make-local-variable 'shell-last-dir)
       (setq shell-last-dir nil)
       (make-local-variable 'shell-dirtrackp)
       (setq shell-dirtrackp t)
       (add-hook 'comint-input-filter-functions 'shell-directory-tracker nil t)
 
       (ansi-color-for-comint-mode-on)
       (define-key py-shell-map [tab] 'ipython-complete)
       ;; Add this so that tab-completion works both in X11 frames and inside
       ;; terminals (such as when emacs is called with -nw).
       (define-key py-shell-map "\t" 'ipython-complete)
       ;;XXX this is really just a cheap hack, it only completes symbols in the
       ;;interactive session -- useful nonetheless.
       (define-key py-mode-map [(meta tab)] 'ipython-complete)
 
       )
     (add-hook 'py-shell-hook 'ipython-shell-hook)
     ;; Regular expression that describes tracebacks for IPython in context and
     ;; verbose mode.
 
     ;;Adapt python-mode settings for ipython.
     ;; (this works for %xmode 'verbose' or 'context')
 
     ;; XXX putative regexps for syntax errors; unfortunately the
     ;;     current python-mode traceback-line-re scheme is too primitive,
     ;;     so it's either matching syntax errors, *or* everything else
     ;;     (XXX: should ask Fernando for a change)
     ;;"^   File \"\\(.*?\\)\", line \\([0-9]+\\).*\n.*\n.*\nSyntaxError:"
     ;;^   File \"\\(.*?\\)\", line \\([0-9]+\\)"
 
     (setq py-traceback-line-re
           "\\(^[^\t >].+?\\.py\\).*\n   +[0-9]+[^\00]*?\n-+> \\([0-9]+\\)+")
 
 
     ;; Recognize the ipython pdb, whose prompt is 'ipdb>' or  'ipydb>'
     ;;instead of '(Pdb)'
     (setq py-pdbtrack-input-prompt "\n[(<]*[Ii]?[Pp]y?db[>)]+ ")
     (setq pydb-pydbtrack-input-prompt "\n[(]*ipydb[>)]+ ")
 
     (setq py-shell-input-prompt-1-regexp "^In \\[[0-9]+\\]: *"
           py-shell-input-prompt-2-regexp "^   [.][.][.]+: *" )
     ;; select a suitable color-scheme
     (unless (member "--colors" py-python-command-args)
       (setq py-python-command-args
             (nconc py-python-command-args
                    (list "--colors"
                          (cond
                            ((eq frame-background-mode 'dark)
                             "Linux")
                            ((eq frame-background-mode 'light)
                             "LightBG")
                            (t ; default (backg-mode isn't always set by XEmacs)
                             "LightBG"))))))
     (unless (equal ipython-backup-of-py-python-command py-python-command)
       (setq ipython-backup-of-py-python-command py-python-command))
     (setq py-python-command ipython-command))
 
 
 ;; MODIFY py-shell so that it loads the editing history
 (defadvice py-shell (around py-shell-with-history)
   "Add persistent command-history support (in
 $PYTHONHISTORY (or \"~/.ipython/history\", if we use IPython)). Also, if
 `py-shell-initial-switch-buffers' is nil, it only switches to *Python* if that
 buffer already exists."
   (if (comint-check-proc "*Python*")
       ad-do-it
     (setq comint-input-ring-file-name
           (if (string-equal py-python-command ipython-command)
               (concat (or (getenv "IPYTHONDIR") "~/.ipython") "/history")
             (or (getenv "PYTHONHISTORY") "~/.python-history.py")))
     (comint-read-input-ring t)
     (let ((buf (current-buffer)))
       ad-do-it
       (unless py-shell-initial-switch-buffers
         (switch-to-buffer-other-window buf)))))
 (ad-activate 'py-shell)
 ;; (defadvice py-execute-region (before py-execute-buffer-ensure-process)
 ;;   "HACK: test that ipython is already running before executing something.
 ;;   Doing this properly seems not worth the bother (unless people actually
 ;;   request it)."
 ;; (unless (comint-check-proc "*Python*")
 ;;     (error "Sorry you have to first do M-x py-shell to send something to ipython.")))
 ;; (ad-activate 'py-execute-region)
 
 (defadvice py-execute-region (around py-execute-buffer-ensure-process)
   "HACK: if `py-shell' is not active or ASYNC is explicitly desired, fall back
   to python instead of ipython."
   (let ((py-which-shell (if (and (comint-check-proc "*Python*") (not async))
 			    py-python-command
 			  ipython-backup-of-py-python-command)))
     ad-do-it))
 (ad-activate 'py-execute-region)
 
 (defun ipython-to-doctest (start end)
   "Transform a cut-and-pasted bit from an IPython session into something that
 looks like it came from a normal interactive python session, so that it can
 be used in doctests. Example:
 
 
     In [1]: import sys
 
     In [2]: sys.stdout.write 'Hi!\n'
     ------> sys.stdout.write ('Hi!\n')
     Hi!
 
     In [3]: 3 + 4
     Out[3]: 7
 
 gets converted to:
 
     >>> import sys
     >>> sys.stdout.write ('Hi!\n')
     Hi!
     >>> 3 + 4
     7
 
 "
   (interactive "*r\n")
   ;(message (format "###DEBUG s:%de:%d" start end))
   (save-excursion
     (save-match-data
       ;; replace ``In [3]: bla`` with ``>>> bla`` and
       ;;         ``... :   bla`` with ``...    bla``
       (goto-char start)
       (while (re-search-forward ipython-de-input-prompt-regexp end t)
         ;(message "finding 1")
         (cond ((match-string 3)         ;continued
                (replace-match "... \\3" t nil))
               (t
                (replace-match ">>> \\1\\2" t nil))))
       ;; replace ``
       (goto-char start)
       (while (re-search-forward ipython-de-output-prompt-regexp end t)
         (replace-match "" t nil)))))
 
 (defvar ipython-completion-command-string
   "print(';'.join(get_ipython().Completer.all_completions('%s'))) #PYTHON-MODE SILENT\n"
   "The string send to ipython to query for all possible completions")
 
 
 ;; xemacs doesn't have `comint-preoutput-filter-functions' so we'll try the
 ;; following wonderful hack to work around this case
 (if (featurep 'xemacs)
     ;;xemacs
     (defun ipython-complete ()
       "Try to complete the python symbol before point. Only knows about the stuff
 in the current *Python* session."
       (interactive)
       (let* ((ugly-return nil)
              (sep ";")
              (python-process (or (get-buffer-process (current-buffer))
                                  ;XXX hack for .py buffers
                                  (get-process py-which-bufname)))
              ;; XXX currently we go backwards to find the beginning of an
              ;; expression part; a more powerful approach in the future might be
              ;; to let ipython have the complete line, so that context can be used
              ;; to do things like filename completion etc.
              (beg (save-excursion (skip-chars-backward "a-z0-9A-Z_." (point-at-bol))
                                   (point)))
              (end (point))
              (pattern (buffer-substring-no-properties beg end))
              (completions nil)
              (completion-table nil)
              completion
              (comint-output-filter-functions
               (append comint-output-filter-functions
                       '(ansi-color-filter-apply
                         (lambda (string)
                                         ;(message (format "DEBUG filtering: %s" string))
                           (setq ugly-return (concat ugly-return string))
                           (delete-region comint-last-output-start
                                          (process-mark (get-buffer-process (current-buffer)))))))))
 	;(message (format "#DEBUG pattern: '%s'" pattern))
         (process-send-string python-process
                               (format ipython-completion-command-string pattern))
         (accept-process-output python-process)
 	
 	;(message (format "DEBUG return: %s" ugly-return))
         (setq completions
               (split-string (substring ugly-return 0 (position ?\n ugly-return)) sep))
         (setq completion-table (loop for str in completions
                                      collect (list str nil)))
         (setq completion (try-completion pattern completion-table))
         (cond ((eq completion t))
               ((null completion)
                (message "Can't find completion for \"%s\"" pattern)
                (ding))
               ((not (string= pattern completion))
                (delete-region beg end)
                (insert completion))
               (t
                (message "Making completion list...")
                (with-output-to-temp-buffer "*Python Completions*"
                  (display-completion-list (all-completions pattern completion-table)))
                (message "Making completion list...%s" "done")))))
   ;; emacs
   (defun ipython-complete ()
     "Try to complete the python symbol before point. Only knows about the stuff
 in the current *Python* session."
     (interactive)
     (let* ((ugly-return nil)
            (sep ";")
            (python-process (or (get-buffer-process (current-buffer))
                                         ;XXX hack for .py buffers
                                (get-process py-which-bufname)))
            ;; XXX currently we go backwards to find the beginning of an
            ;; expression part; a more powerful approach in the future might be
            ;; to let ipython have the complete line, so that context can be used
            ;; to do things like filename completion etc.
            (beg (save-excursion (skip-chars-backward "a-z0-9A-Z_./" (point-at-bol))
                                 (point)))
            (end (point))
            (pattern (buffer-substring-no-properties beg end))
            (completions nil)
            (completion-table nil)
            completion
          (comint-preoutput-filter-functions
           (append comint-preoutput-filter-functions
                   '(ansi-color-filter-apply
                     (lambda (string)
                       (setq ugly-return (concat ugly-return string))
                       "")))))
       (process-send-string python-process
                             (format ipython-completion-command-string pattern))
       (accept-process-output python-process)
       (setq completions
             (split-string (substring ugly-return 0 (position ?\n ugly-return)) sep))
                                         ;(message (format "DEBUG completions: %S" completions))
       (setq completion-table (loop for str in completions
                                    collect (list str nil)))
       (setq completion (try-completion pattern completion-table))
       (cond ((eq completion t))
             ((null completion)
              (message "Can't find completion for \"%s\"" pattern)
              (ding))
             ((not (string= pattern completion))
              (delete-region beg end)
              (insert completion))
             (t
              (message "Making completion list...")
              (with-output-to-temp-buffer "*IPython Completions*"
                (display-completion-list (all-completions pattern completion-table)))
              (message "Making completion list...%s" "done")))))
 )
 
 ;;; autoindent support: patch sent in by Jin Liu <[e-mail]>,
 ;;; originally written by [e-mail]
 ;;; Minor modifications by fperez for xemacs compatibility.
 
 (defvar ipython-autoindent t
  "If non-nil, enable autoindent for IPython shell through python-mode.")
 
 (defvar ipython-indenting-buffer-name "*IPython Indentation Calculation*"
  "Temporary buffer for indenting multiline statement.")
 
 (defun ipython-get-indenting-buffer ()
  "Return a temporary buffer set in python-mode. Create one if necessary."
  (let ((buf (get-buffer-create ipython-indenting-buffer-name)))
    (set-buffer buf)
    (unless (eq major-mode 'python-mode)
      (python-mode))
    buf))
 
 (defvar ipython-indentation-string nil
  "Indentation for the next line in a multiline statement.")
 
 (defun ipython-send-and-indent ()
  "Send the current line to IPython, and calculate the indentation for
 the next line."
  (interactive)
  (if ipython-autoindent
      (let ((line (buffer-substring (point-at-bol) (point)))
            (after-prompt1)
            (after-prompt2))
        (save-excursion
            (comint-bol t)
            (if (looking-at py-shell-input-prompt-1-regexp)
                (setq after-prompt1 t)
              (setq after-prompt2 (looking-at py-shell-input-prompt-2-regexp)))
            (with-current-buffer (ipython-get-indenting-buffer)
              (when after-prompt1
                (erase-buffer))
              (when (or after-prompt1 after-prompt2)
                (delete-region (point-at-bol) (point))
                (insert line)
                (newline-and-indent))))))
  ;; send input line to ipython interpreter
  (comint-send-input))
 
 (defun ipython-indentation-hook (string)
  "Insert indentation string if py-shell-input-prompt-2-regexp
 matches last process output."
  (let* ((start-marker (or comint-last-output-start
                           (point-min-marker)))
         (end-marker (process-mark (get-buffer-process (current-buffer))))
         (text (ansi-color-filter-apply (buffer-substring start-marker end-marker))))
    ;; XXX if `text' matches both pattern, it MUST be the last prompt-2
    (when (and (string-match py-shell-input-prompt-2-regexp text)
 	      (not (string-match "\n$" text)))
      (with-current-buffer (ipython-get-indenting-buffer)
        (setq ipython-indentation-string
 	     (buffer-substring (point-at-bol) (point))))
      (goto-char end-marker)
      (insert ipython-indentation-string)
      (setq ipython-indentation-string nil))))
 
 (add-hook 'py-shell-hook
          (lambda ()
            (add-hook 'comint-output-filter-functions
                      'ipython-indentation-hook)))
 
 (define-key py-shell-map (kbd "RET") 'ipython-send-and-indent)
 ;;; / end autoindent support
 
 (provide 'ipython)

docs/source/development/gitwash/git_links.txt

@@ -1,67 +1,67 b''
 .. This (-*- rst -*-) format file contains commonly used link targets
    and name substitutions.  It may be included in many files,
    therefore it should only contain link targets and name
    substitutions.  Try grepping for "^\.\. _" to find plausible
    candidates for this list.  
 
 .. NOTE: reST targets are
    __not_case_sensitive__, so only one target definition is needed for
    nipy, NIPY, Nipy, etc...
 
 .. PROJECTNAME placeholders
 .. _PROJECTNAME: http://neuroimaging.scipy.org
 .. _`PROJECTNAME github`: http://github.com/nipy
 .. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
 
 .. nipy
 .. _nipy: http://nipy.org/nipy
 .. _`nipy github`: http://github.com/nipy/nipy
 .. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
 
 .. ipython
-.. _ipython: http://ipython.scipy.org
+.. _ipython: http://ipython.org
 .. _`ipython github`: http://github.com/ipython/ipython
 .. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
 
 .. nipy
 .. _dipy: http://nipy.org/dipy
 .. _`dipy github`: http://github.com/Garyfallidis/dipy
 .. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
 
 .. git stuff
 .. _git: http://git-scm.com/
 .. _github: http://github.com
 .. _github help: http://help.github.com
 .. _msysgit: http://code.google.com/p/msysgit/downloads/list
 .. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list
 .. _subversion: http://subversion.tigris.org/
 .. _git cheat sheet: http://github.com/guides/git-cheat-sheet
 .. _pro git book: http://progit.org/
 .. _git svn crash course: http://git-scm.com/course/svn.html
 .. _learn.github: http://learn.github.com/
 .. _network graph visualizer: http://github.com/blog/39-say-hello-to-the-network-graph-visualizer
 .. _git user manual: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
 .. _git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
 .. _git community book: http://book.git-scm.com/
 .. _git ready: http://www.gitready.com/
 .. _git casts: http://www.gitcasts.com/
 .. _Fernando's git page: http://www.fperez.org/py4science/git.html
 .. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
 .. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/
 .. _git clone: http://www.kernel.org/pub/software/scm/git/docs/git-clone.html
 .. _git checkout: http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html
 .. _git commit: http://www.kernel.org/pub/software/scm/git/docs/git-commit.html
 .. _git push: http://www.kernel.org/pub/software/scm/git/docs/git-push.html
 .. _git pull: http://www.kernel.org/pub/software/scm/git/docs/git-pull.html
 .. _git add: http://www.kernel.org/pub/software/scm/git/docs/git-add.html
 .. _git status: http://www.kernel.org/pub/software/scm/git/docs/git-status.html
 .. _git diff: http://www.kernel.org/pub/software/scm/git/docs/git-diff.html
 .. _git log: http://www.kernel.org/pub/software/scm/git/docs/git-log.html
 .. _git branch: http://www.kernel.org/pub/software/scm/git/docs/git-branch.html
 .. _git remote: http://www.kernel.org/pub/software/scm/git/docs/git-remote.html
 .. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html
 .. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git management: http://kerneltrap.org/Linux/Git_Management
 .. _linux git workflow: http://www.mail-archive.com/[e-mail]/msg39091.html
 .. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html

docs/source/links.rst

@@ -1,74 +1,74 b''
 .. This (-*- rst -*-) format file contains commonly used link targets
    and name substitutions.  It may be included in many files,
    therefore it should only contain link targets and name
    substitutions.  Try grepping for "^\.\. _" to find plausible
    candidates for this list.  
 
    NOTE: this file must have an extension *opposite* to that of the main reST
    files in the manuals, so that we can include it with ".. include::"
    directives, but without triggering warnings from Sphinx for not being listed
    in any toctree.  Since IPython uses .txt for the main files, this wone will
    use .rst.
    
    NOTE: reST targets are
    __not_case_sensitive__, so only one target definition is needed for
    ipython, IPython, etc.
 
    NOTE: Some of these were taken from the nipy links compendium.
 
 .. Main IPython links
-.. _ipython: http://ipython.scipy.org
-.. _`ipython manual`: http://ipython.scipy.org/doc/manual/html
+.. _ipython: http://ipython.org
+.. _`ipython manual`: http://ipython.org/documentation.html
 .. _ipython_github: http://github.com/ipython/ipython/
 .. _ipython_github_repo: http://github.com/ipython/ipython/
 .. _ipython_downloads: http://ipython.scipy.org/dist
 .. _ipython_pypi: http://pypi.python.org/pypi/ipython
 
 .. _ZeroMQ: http://zeromq.org
 
 .. Documentation tools and related links
 .. _graphviz: http://www.graphviz.org
 .. _Sphinx: http://sphinx.pocoo.org
 .. _`Sphinx reST`: http://sphinx.pocoo.org/rest.html
 .. _sampledoc: http://matplotlib.sourceforge.net/sampledoc
 .. _reST: http://docutils.sourceforge.net/rst.html
 .. _docutils: http://docutils.sourceforge.net
 .. _lyx: http://www.lyx.org
 .. _pep8: http://www.python.org/dev/peps/pep-0008
 .. _numpy_coding_guide: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
 
 .. Licenses
 .. _GPL: http://www.gnu.org/licenses/gpl.html
 .. _BSD: http://www.opensource.org/licenses/bsd-license.php
 .. _LGPL: http://www.gnu.org/copyleft/lesser.html
 
 .. Other python projects
 .. _numpy: http://numpy.scipy.org
 .. _scipy: http://www.scipy.org
 .. _scipy_conference: http://conference.scipy.org
 .. _matplotlib: http://matplotlib.sourceforge.net
 .. _pythonxy: http://www.pythonxy.com
 .. _ETS: http://code.enthought.com/projects/tool-suite.php
 .. _EPD: http://www.enthought.com/products/epd.php
 .. _python: http://www.python.org
 .. _mayavi: http://code.enthought.com/projects/mayavi
 .. _sympy: http://code.google.com/p/sympy
 .. _sage: http://sagemath.org
 .. _pydy: http://code.google.com/p/pydy
 .. _vpython: http://vpython.org
 .. _cython: http://cython.org
 .. _software carpentry: http://software-carpentry.org
 
 .. Not so python scientific computing tools
 .. _matlab: http://www.mathworks.com
 .. _VTK: http://vtk.org
 
 .. Other organizations
 .. _enthought: http://www.enthought.com
 .. _kitware: http://www.kitware.com
 .. _netlib: http://netlib.org
 
 .. Other tools and projects
 .. _indefero: http://www.indefero.net
 .. _git: http://git-scm.com
 .. _github: http://github.com

docs/source/parallel/parallel_winhpc.txt

@@ -1,334 +1,334 b''
 ============================================
 Getting started with Windows HPC Server 2008
 ============================================
 
 .. note::
 
     Not adapted to zmq yet
 
 Introduction
 ============
 
 The Python programming language is an increasingly popular language for
 numerical computing. This is due to a unique combination of factors. First,
 Python is a high-level and *interactive* language that is well matched to
 interactive numerical work. Second, it is easy (often times trivial) to
 integrate legacy C/C++/Fortran code into Python. Third, a large number of
 high-quality open source projects provide all the needed building blocks for
 numerical computing: numerical arrays (NumPy), algorithms (SciPy), 2D/3D
 Visualization (Matplotlib, Mayavi, Chaco), Symbolic Mathematics (Sage, Sympy)
 and others.
 
 The IPython project is a core part of this open-source toolchain and is
 focused on creating a comprehensive environment for interactive and
 exploratory computing in the Python programming language. It enables all of
 the above tools to be used interactively and consists of two main components:
 
 * An enhanced interactive Python shell with support for interactive plotting
   and visualization.
 * An architecture for interactive parallel computing.
 
 With these components, it is possible to perform all aspects of a parallel
 computation interactively. This type of workflow is particularly relevant in
 scientific and numerical computing where algorithms, code and data are
 continually evolving as the user/developer explores a problem. The broad
 treads in computing (commodity clusters, multicore, cloud computing, etc.)
 make these capabilities of IPython particularly relevant.
 
 While IPython is a cross platform tool, it has particularly strong support for
 Windows based compute clusters running Windows HPC Server 2008. This document
 describes how to get started with IPython on Windows HPC Server 2008. The
 content and emphasis here is practical: installing IPython, configuring
 IPython to use the Windows job scheduler and running example parallel programs
 interactively. A more complete description of IPython's parallel computing
 capabilities can be found in IPython's online documentation
-(http://ipython.scipy.org/moin/Documentation).
+(http://ipython.org/documentation.html).
 
 Setting up your Windows cluster
 ===============================
 
 This document assumes that you already have a cluster running Windows
 HPC Server 2008. Here is a broad overview of what is involved with setting up
 such a cluster:
 
 1. Install Windows Server 2008 on the head and compute nodes in the cluster.
 2. Setup the network configuration on each host. Each host should have a 
    static IP address.
 3. On the head node, activate the "Active Directory Domain Services" role 
    and make the head node the domain controller.
 4. Join the compute nodes to the newly created Active Directory (AD) domain.
 5. Setup user accounts in the domain with shared home directories.
 6. Install the HPC Pack 2008 on the head node to create a cluster.
 7. Install the HPC Pack 2008 on the compute nodes.
 
 More details about installing and configuring Windows HPC Server 2008 can be
 found on the Windows HPC Home Page (http://www.microsoft.com/hpc). Regardless
 of what steps you follow to set up your cluster, the remainder of this
 document will assume that:
 
 * There are domain users that can log on to the AD domain and submit jobs
   to the cluster scheduler.
 * These domain users have shared home directories. While shared home
   directories are not required to use IPython, they make it much easier to
   use IPython.
 
 Installation of IPython and its dependencies
 ============================================
 
 IPython and all of its dependencies are freely available and open source.
 These packages provide a powerful and cost-effective approach to numerical and
 scientific computing on Windows. The following dependencies are needed to run
 IPython on Windows:
 
 * Python 2.6 or 2.7 (http://www.python.org)
 * pywin32 (http://sourceforge.net/projects/pywin32/)
 * PyReadline (https://launchpad.net/pyreadline)
 * pyzmq (http://github.com/zeromq/pyzmq/downloads)
-* IPython (http://ipython.scipy.org)
+* IPython (http://ipython.org)
 
 In addition, the following dependencies are needed to run the demos described
 in this document.
 
 * NumPy and SciPy (http://www.scipy.org)
 * Matplotlib (http://matplotlib.sourceforge.net/)
 
 The easiest way of obtaining these dependencies is through the Enthought
 Python Distribution (EPD) (http://www.enthought.com/products/epd.php). EPD is
 produced by Enthought, Inc. and contains all of these packages and others in a
 single installer and is available free for academic users. While it is also
 possible to download and install each package individually, this is a tedious
 process. Thus, we highly recommend using EPD to install these packages on
 Windows.
 
 Regardless of how you install the dependencies, here are the steps you will
 need to follow:
 
 1. Install all of the packages listed above, either individually or using EPD
    on the head node, compute nodes and user workstations.
 
 2. Make sure that :file:`C:\\Python27` and :file:`C:\\Python27\\Scripts` are
    in the system :envvar:`%PATH%` variable on each node.
 
 3. Install the latest development version of IPython. This can be done by
    downloading the the development version from the IPython website
-   (http://ipython.scipy.org) and following the installation instructions.
+   (http://ipython.org) and following the installation instructions.
 
 Further details about installing IPython or its dependencies can be found in
-the online IPython documentation (http://ipython.scipy.org/moin/Documentation)
+the online IPython documentation (http://ipython.org/documentation.html)
 Once you are finished with the installation, you can try IPython out by
 opening a Windows Command Prompt and typing ``ipython``. This will
 start IPython's interactive shell and you should see something like the
 following screenshot:
 
 .. image:: ipython_shell.*
 
 Starting an IPython cluster
 ===========================
 
 To use IPython's parallel computing capabilities, you will need to start an
 IPython cluster. An IPython cluster consists of one controller and multiple
 engines:
 
 IPython controller
     The IPython controller manages the engines and acts as a gateway between 
     the engines and the client, which runs in the user's interactive IPython
     session. The controller is started using the :command:`ipcontroller`
     command.
 
 IPython engine
     IPython engines run a user's Python code in parallel on the compute nodes. 
     Engines are starting using the :command:`ipengine` command.
 
 Once these processes are started, a user can run Python code interactively and
 in parallel on the engines from within the IPython shell using an appropriate
 client. This includes the ability to interact with, plot and visualize data
 from the engines.
 
 IPython has a command line program called :command:`ipcluster` that automates
 all aspects of starting the controller and engines on the compute nodes.
 :command:`ipcluster` has full support for the Windows HPC job scheduler,
 meaning that :command:`ipcluster` can use this job scheduler to start the
 controller and engines. In our experience, the Windows HPC job scheduler is
 particularly well suited for interactive applications, such as IPython. Once
 :command:`ipcluster` is configured properly, a user can start an IPython
 cluster from their local workstation almost instantly, without having to log
 on to the head node (as is typically required by Unix based job schedulers).
 This enables a user to move seamlessly between serial and parallel
 computations.
 
 In this section we show how to use :command:`ipcluster` to start an IPython
 cluster using the Windows HPC Server 2008 job scheduler. To make sure that
 :command:`ipcluster` is installed and working properly, you should first try
 to start an IPython cluster on your local host. To do this, open a Windows
 Command Prompt and type the following command::
 
     ipcluster start n=2
 
 You should see a number of messages printed to the screen, ending with 
 "IPython cluster: started". The result should look something like the following
 screenshot:
 
 .. image:: ipcluster_start.*
 
 At this point, the controller and two engines are running on your local host.
 This configuration is useful for testing and for situations where you want to
 take advantage of multiple cores on your local computer. 
 
 Now that we have confirmed that :command:`ipcluster` is working properly, we
 describe how to configure and run an IPython cluster on an actual compute
 cluster running Windows HPC Server 2008. Here is an outline of the needed
 steps:
 
 1. Create a cluster profile using: ``ipython profile create --parallel profile=mycluster``
 
 2. Edit configuration files in the directory :file:`.ipython\\cluster_mycluster`
 
 3. Start the cluster using: ``ipcluser start profile=mycluster n=32``
 
 Creating a cluster profile
 --------------------------
 
 In most cases, you will have to create a cluster profile to use IPython on a
 cluster. A cluster profile is a name (like "mycluster") that is associated
 with a particular cluster configuration. The profile name is used by
 :command:`ipcluster` when working with the cluster.
 
 Associated with each cluster profile is a cluster directory. This cluster
 directory is a specially named directory (typically located in the
 :file:`.ipython` subdirectory of your home directory) that contains the
 configuration files for a particular cluster profile, as well as log files and
 security keys. The naming convention for cluster directories is:
 :file:`profile_<profile name>`. Thus, the cluster directory for a profile named
 "foo" would be :file:`.ipython\\cluster_foo`.
 
 To create a new cluster profile (named "mycluster") and the associated cluster
 directory, type the following command at the Windows Command Prompt::
 
     ipython profile create --parallel profile=mycluster
 
 The output of this command is shown in the screenshot below. Notice how
 :command:`ipcluster` prints out the location of the newly created cluster
 directory.
 
 .. image:: ipcluster_create.*
 
 Configuring a cluster profile
 -----------------------------
 
 Next, you will need to configure the newly created cluster profile by editing
 the following configuration files in the cluster directory:
 
 * :file:`ipcluster_config.py`
 * :file:`ipcontroller_config.py`
 * :file:`ipengine_config.py`
 
 When :command:`ipcluster` is run, these configuration files are used to 
 determine how the engines and controller will be started. In most cases,
 you will only have to set a few of the attributes in these files.
 
 To configure :command:`ipcluster` to use the Windows HPC job scheduler, you
 will need to edit the following attributes in the file
 :file:`ipcluster_config.py`::
 
     # Set these at the top of the file to tell ipcluster to use the
     # Windows HPC job scheduler.
     c.IPClusterStart.controller_launcher = \
         'IPython.parallel.apps.launcher.WindowsHPCControllerLauncher'
     c.IPClusterEngines.engine_launcher = \
         'IPython.parallel.apps.launcher.WindowsHPCEngineSetLauncher'
 
     # Set these to the host name of the scheduler (head node) of your cluster.
     c.WindowsHPCControllerLauncher.scheduler = 'HEADNODE'
     c.WindowsHPCEngineSetLauncher.scheduler = 'HEADNODE'
 
 There are a number of other configuration attributes that can be set, but
 in most cases these will be sufficient to get you started.
 
 .. warning::
     If any of your configuration attributes involve specifying the location
     of shared directories or files, you must make sure that you use UNC paths
     like :file:`\\\\host\\share`. It is also important that you specify
     these paths using raw Python strings: ``r'\\host\share'`` to make sure
     that the backslashes are properly escaped.
 
 Starting the cluster profile
 ----------------------------
 
 Once a cluster profile has been configured, starting an IPython cluster using
 the profile is simple::
 
     ipcluster start profile=mycluster n=32
 
 The ``-n`` option tells :command:`ipcluster` how many engines to start (in
 this case 32). Stopping the cluster is as simple as typing Control-C.
 
 Using the HPC Job Manager
 -------------------------
 
 When ``ipcluster start`` is run the first time, :command:`ipcluster` creates
 two XML job description files in the cluster directory:
 
 * :file:`ipcontroller_job.xml`
 * :file:`ipengineset_job.xml`
 
 Once these files have been created, they can be imported into the HPC Job
 Manager application. Then, the controller and engines for that profile can be
 started using the HPC Job Manager directly, without using :command:`ipcluster`.
 However, anytime the cluster profile is re-configured, ``ipcluster start``
 must be run again to regenerate the XML job description files. The
 following screenshot shows what the HPC Job Manager interface looks like
 with a running IPython cluster.
 
 .. image:: hpc_job_manager.*
 
 Performing a simple interactive parallel computation
 ====================================================
 
 Once you have started your IPython cluster, you can start to use it. To do
 this, open up a new Windows Command Prompt and start up IPython's interactive
 shell by typing::
 
     ipython
 
 Then you can create a :class:`MultiEngineClient` instance for your profile and
 use the resulting instance to do a simple interactive parallel computation. In
 the code and screenshot that follows, we take a simple Python function and
 apply it to each element of an array of integers in parallel using the
 :meth:`MultiEngineClient.map` method:
 
 .. sourcecode:: ipython
 
     In [1]: from IPython.parallel import *
 
     In [2]: c = MultiEngineClient(profile='mycluster')
 
     In [3]: mec.get_ids()
     Out[3]: [0, 1, 2, 3, 4, 5, 67, 8, 9, 10, 11, 12, 13, 14]
 
     In [4]: def f(x):
        ...:     return x**10
 
     In [5]: mec.map(f, range(15))  # f is applied in parallel
     Out[5]:
     [0,
      1,
      1024,
      59049,
      1048576,
      9765625,
      60466176,
      282475249,
      1073741824,
      3486784401L,
      10000000000L,
      25937424601L,
      61917364224L,
      137858491849L,
      289254654976L]
 
 The :meth:`map` method has the same signature as Python's builtin :func:`map`
 function, but runs the calculation in parallel. More involved examples of using
 :class:`MultiEngineClient` are provided in the examples that follow.
 
 .. image:: mec_simple.*