initial_config.txt
237 lines
| 10.0 KiB
| text/plain
|
TextLexer
Brian E Granger
|
r1258 | .. _initial config: | |
========================================= | |||
Initial configuration of your environment | |||
========================================= | |||
This section will help you set various things in your environment for | |||
your IPython sessions to be as efficient as possible. All of IPython's | |||
configuration information, along with several example files, is stored | |||
in a directory named by default $HOME/.ipython. You can change this by | |||
defining the environment variable IPYTHONDIR, or at runtime with the | |||
command line option -ipythondir. | |||
If all goes well, the first time you run IPython it should | |||
automatically create a user copy of the config directory for you, | |||
based on its builtin defaults. You can look at the files it creates to | |||
learn more about configuring the system. The main file you will modify | |||
to configure IPython's behavior is called ipythonrc (with a .ini | |||
extension under Windows), included for reference in `ipythonrc`_ | |||
section. This file is very commented and has many variables you can | |||
change to suit your taste, you can find more details in | |||
Sec. customization_. Here we discuss the basic things you will want to | |||
make sure things are working properly from the beginning. | |||
.. _Accessing help: | |||
Access to the Python help system | |||
================================ | |||
This is true for Python in general (not just for IPython): you should | |||
have an environment variable called PYTHONDOCS pointing to the directory | |||
where your HTML Python documentation lives. In my system it's | |||
/usr/share/doc/python-docs-2.3.4/html, check your local details or ask | |||
your systems administrator. | |||
This is the directory which holds the HTML version of the Python | |||
manuals. Unfortunately it seems that different Linux distributions | |||
package these files differently, so you may have to look around a bit. | |||
Below I show the contents of this directory on my system for reference:: | |||
[html]> ls | |||
about.dat acks.html dist/ ext/ index.html lib/ modindex.html | |||
stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css | |||
You should really make sure this variable is correctly set so that | |||
Python's pydoc-based help system works. It is a powerful and convenient | |||
system with full access to the Python manuals and all modules accessible | |||
to you. | |||
Under Windows it seems that pydoc finds the documentation automatically, | |||
so no extra setup appears necessary. | |||
Editor | |||
====== | |||
The %edit command (and its alias %ed) will invoke the editor set in your | |||
environment as EDITOR. If this variable is not set, it will default to | |||
vi under Linux/Unix and to notepad under Windows. You may want to set | |||
this variable properly and to a lightweight editor which doesn't take | |||
too long to start (that is, something other than a new instance of | |||
Emacs). This way you can edit multi-line code quickly and with the power | |||
of a real editor right inside IPython. | |||
If you are a dedicated Emacs user, you should set up the Emacs server so | |||
that new requests are handled by the original process. This means that | |||
almost no time is spent in handling the request (assuming an Emacs | |||
process is already running). For this to work, you need to set your | |||
EDITOR environment variable to 'emacsclient'. The code below, supplied | |||
by Francois Pinard, can then be used in your .emacs file to enable the | |||
server:: | |||
(defvar server-buffer-clients) | |||
(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) | |||
(server-start) | |||
(defun fp-kill-server-with-buffer-routine () | |||
(and server-buffer-clients (server-done))) | |||
(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) | |||
You can also set the value of this editor via the commmand-line option | |||
'-editor' or in your ipythonrc file. This is useful if you wish to use | |||
specifically for IPython an editor different from your typical default | |||
(and for Windows users who tend to use fewer environment variables). | |||
Color | |||
===== | |||
The default IPython configuration has most bells and whistles turned on | |||
(they're pretty safe). But there's one that may cause problems on some | |||
systems: the use of color on screen for displaying information. This is | |||
very useful, since IPython can show prompts and exception tracebacks | |||
with various colors, display syntax-highlighted source code, and in | |||
general make it easier to visually parse information. | |||
The following terminals seem to handle the color sequences fine: | |||
* Linux main text console, KDE Konsole, Gnome Terminal, E-term, | |||
rxvt, xterm. | |||
* CDE terminal (tested under Solaris). This one boldfaces light colors. | |||
* (X)Emacs buffers. See the emacs_ section for more details on | |||
using IPython with (X)Emacs. | |||
* A Windows (XP/2k) command prompt with pyreadline_. | |||
* A Windows (XP/2k) CygWin shell. Although some users have reported | |||
problems; it is not clear whether there is an issue for everyone | |||
or only under specific configurations. If you have full color | |||
support under cygwin, please post to the IPython mailing list so | |||
this issue can be resolved for all users. | |||
These have shown problems: | |||
* Windows command prompt in WinXP/2k logged into a Linux machine via | |||
telnet or ssh. | |||
* Windows native command prompt in WinXP/2k, without Gary Bishop's | |||
extensions. Once Gary's readline library is installed, the normal | |||
WinXP/2k command prompt works perfectly. | |||
Currently the following color schemes are available: | |||
* NoColor: uses no color escapes at all (all escapes are empty '' '' | |||
strings). This 'scheme' is thus fully safe to use in any terminal. | |||
* Linux: works well in Linux console type environments: dark | |||
background with light fonts. It uses bright colors for | |||
information, so it is difficult to read if you have a light | |||
colored background. | |||
* LightBG: the basic colors are similar to those in the Linux scheme | |||
but darker. It is easy to read in terminals with light backgrounds. | |||
IPython uses colors for two main groups of things: prompts and | |||
tracebacks which are directly printed to the terminal, and the object | |||
introspection system which passes large sets of data through a pager. | |||
Input/Output prompts and exception tracebacks | |||
============================================= | |||
You can test whether the colored prompts and tracebacks work on your | |||
system interactively by typing '%colors Linux' at the prompt (use | |||
'%colors LightBG' if your terminal has a light background). If the input | |||
prompt shows garbage like:: | |||
[0;32mIn [[1;32m1[0;32m]: [0;00m | |||
instead of (in color) something like:: | |||
In [1]: | |||
this means that your terminal doesn't properly handle color escape | |||
sequences. You can go to a 'no color' mode by typing '%colors NoColor'. | |||
You can try using a different terminal emulator program (Emacs users, | |||
see below). To permanently set your color preferences, edit the file | |||
$HOME/.ipython/ipythonrc and set the colors option to the desired value. | |||
Object details (types, docstrings, source code, etc.) | |||
===================================================== | |||
IPython has a set of special functions for studying the objects you | |||
are working with, discussed in detail in Sec. `dynamic object | |||
information`_. But this system relies on passing information which is | |||
longer than your screen through a data pager, such as the common Unix | |||
less and more programs. In order to be able to see this information in | |||
color, your pager needs to be properly configured. I strongly | |||
recommend using less instead of more, as it seems that more simply can | |||
not understand colored text correctly. | |||
In order to configure less as your default pager, do the following: | |||
1. Set the environment PAGER variable to less. | |||
2. Set the environment LESS variable to -r (plus any other options | |||
you always want to pass to less by default). This tells less to | |||
properly interpret control sequences, which is how color | |||
information is given to your terminal. | |||
For the csh or tcsh shells, add to your ~/.cshrc file the lines:: | |||
setenv PAGER less | |||
setenv LESS -r | |||
There is similar syntax for other Unix shells, look at your system | |||
documentation for details. | |||
If you are on a system which lacks proper data pagers (such as Windows), | |||
IPython will use a very limited builtin pager. | |||
.. _emacs: | |||
(X)Emacs configuration | |||
====================== | |||
Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, | |||
currently (X)Emacs and IPython get along very well. | |||
Important note: You will need to use a recent enough version of | |||
python-mode.el, along with the file ipython.el. You can check that the | |||
version you have of python-mode.el is new enough by either looking at | |||
the revision number in the file itself, or asking for it in (X)Emacs via | |||
M-x py-version. Versions 4.68 and newer contain the necessary fixes for | |||
proper IPython support. | |||
The file ipython.el is included with the IPython distribution, in the | |||
documentation directory (where this manual resides in PDF and HTML | |||
formats). | |||
Once you put these files in your Emacs path, all you need in your .emacs | |||
file is:: | |||
(require 'ipython) | |||
This should give you full support for executing code snippets via | |||
IPython, opening IPython as your Python shell via C-c !, etc. | |||
If you happen to get garbage instead of colored prompts as described in | |||
the previous section, you may need to set also in your .emacs file:: | |||
(setq ansi-color-for-comint-mode t) | |||
Notes: | |||
* There is one caveat you should be aware of: you must start the | |||
IPython shell before attempting to execute any code regions via | |||
``C-c |``. Simply type C-c ! to start IPython before passing any code | |||
regions to the interpreter, and you shouldn't experience any | |||
problems. | |||
This is due to a bug in Python itself, which has been fixed for | |||
Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [ | |||
737947 ]). | |||
* The (X)Emacs support is maintained by Alexander Schmolck, so all | |||
comments/requests should be directed to him through the IPython | |||
mailing lists. | |||
* This code is still somewhat experimental so it's a bit rough | |||
around the edges (although in practice, it works quite well). | |||
* Be aware that if you customize py-python-command previously, this | |||
value will override what ipython.el does (because loading the | |||
customization variables comes later). |