This section will help you set various things in your environment for your IPython sessions to be as efficient as possible. All of IPython's configuration information, along with several example files, is stored in a directory named by default $HOME/.ipython. You can change this by defining the environment variable IPYTHONDIR, or at runtime with the command line option -ipythondir.
If all goes well, the first time you run IPython it should automatically create a user copy of the config directory for you, based on its builtin defaults. You can look at the files it creates to learn more about configuring the system. The main file you will modify to configure IPython's behavior is called ipythonrc, included for reference in Sec. 7.1. This file is very commented and has many variables you can change to suit your taste, you can find more details in Sec. 7. Here we discuss the basic things you will want to make sure things are working properly from the beginning.
This is true for Python 2.1 in general (not just for IPython): you should have an environment variable called PYTHONDOCS pointing to the directory where your HTML Python documentation lives. In my system it's /usr/share/doc/python-docs-2.1.1/html, check your local details or ask your systems administrator.
This is the directory which holds the HTML version of the Python manuals. Unfortunately it seems that different Linux distributions package these files differently, so you may have to look around a bit. Below I show the contents of this directory on my system for reference:
[html]> ls
about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat
tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
You should really make sure this variable is correctly set so that Python's pydoc-based help system works. It is a powerful and convenient system with full access to the Python manuals and all modules accessible to you.
Under Windows it seems that pydoc finds the documentation automatically, so no extra setup appears necessary.
The @edit command (and its alias @ed) will invoke the editor set in your environment as EDITOR. If this variable is not set, it will default to vi under Linux/Unix and to notepad under Windows. You may want to set this variable properly and to a lightweight editor which doesn't take too long to start (that is, something other than a new instance of Emacs). This way you can edit multi-line code quickly and with the power of a real editor right inside IPython.
If you are a dedicated Emacs user, you should set up the Emacs server so that new requests are handled by the original process. This means that almost no time is spent in handling the request (assuming an Emacs process is already running). For this wo work, you need to set your EDITOR environment variable to 'emacsclient'. The code below, supplied by François Pinard, can then be used in your .emacs file to enable the server:
(defvar server-buffer-clients)
(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
(server-start)
(defun fp-kill-server-with-buffer-routine ()
(and server-buffer-clients (server-done)))
(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
You can also set the value of this editor via the commmand-line option '-editor' or in your ipythonrc file. This is useful if you wish to use specifically for IPython an editor different from your typical default (and for Windows users which typically don't set environment variables).
The default IPython configuration has most bells and whistles turned on (they're pretty safe). But there's one that may cause problems on some systems: the use of color on screen for displaying information. This is very useful, since IPython can show prompts and exception tracebacks with various colors, display syntax-highlighted source code, and in general make it easier to visually parse information. But not all terminals out there have reliable support for on-screen color, so these options are not enabled by default to avoid confusing new users with on-screen garbage.
The following terminals seem to handle the color sequences fine:
You can test whether the colored prompts and tracebacks work on your system interactively
by typing '@colors Linux' at the prompt (use '@colors LightBG'
if your terminal has a light background). If the input prompt shows garbage like:
[0;32mIn [[1;32m1[0;32m]: [0;00m
instead of (in color) something like:
In [1]:
this means that your terminal doesn't properly handle color escape sequences. You
can go to a 'no color' mode by typing '@colors NoColor'.
You can try using a different terminal emulator program. To permanently set your color preferences, edit the file $HOME/.ipython/ipythonrc and set the colors option to the desired value.
IPython has a set of special functions for studying the objects you are working with, discussed in detail in Sec. 6.3. But this system relies on passing information which is longer than your screen through a data pager, such as the common Unix less and more programs. In order to be able to see this information in color, your pager needs to be properly configured. I strongly recommend using less instead of more, as it seems that more simply can not understand colored text correctly.
In order to configure less as your default pager, do the following:
setenv PAGER less
setenv LESS -r
There is similar syntax for other Unix shells, look at your system documentation for details.
If you are on a system which lacks proper data pagers (such as Windows), IPython will use a very limited builtin pager.
Thanks to the work of Alexander Schmolck, currently (X)Emacs and IPython get along very well. You will need to use a recent version of python-mode.el, along with the file ipython.el. At the IPython website's download section, you will find a tarball containing both of these files. Once you put them in your Emacs path, all you need in your .emacs file is:
(require 'ipython)
This should give you full support for executing code snippets via IPython, opening IPython as your Python shell via C-c !, etc.