initial_config.txt
249 lines
| 10.5 KiB
| text/plain
|
TextLexer
|
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. | ||||
|
r1695 | 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 | ||||
:ref:`here <ipythonrc>`. This file is very commented and has many variables you | ||||
can change to suit your taste, you can find more details :ref:`here | ||||
<customization>`. Here we discuss the basic things you will want to make sure | ||||
things are working properly from the beginning. | ||||
|
r1258 | |||
|
r1695 | .. _accessing_help: | ||
|
r1258 | |||
Access to the Python help system | ||||
================================ | ||||
|
r1695 | 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 | ||||
:file:`/usr/share/doc/python-doc/html`, check your local details or ask your | ||||
systems administrator. | ||||
|
r1258 | |||
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:: | ||||
|
r1329 | [html]> ls | ||
|
r1695 | about.html dist/ icons/ lib/ python2.5.devhelp.gz whatsnew/ | ||
acks.html doc/ index.html mac/ ref/ | ||||
api/ ext/ inst/ modindex.html tut/ | ||||
|
r1258 | |||
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:: | ||||
|
r1329 | (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))) | ||||
|
r1258 | (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. | ||||
|
r1695 | .. _pyreadline: https://code.launchpad.net/pyreadline | ||
|
r1258 | 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 | ||||
|
r1329 | |||
|
r1258 | instead of (in color) something like:: | ||
|
r1329 | |||
|
r1258 | In [1]: | ||
|
r1329 | |||
|
r1258 | 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.) | ||||
===================================================== | ||||
|
r1695 | IPython has a set of special functions for studying the objects you are working | ||
with, discussed in detail :ref:`here <dynamic_object_info>`. 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 | ||||
|
r1258 | 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. | ||||
|
r2113 | For the bash shell, add to your ~/.bashrc file the lines:: | ||
export PAGER=less | ||||
export LESS=-r | ||||
|
r1258 | For the csh or tcsh shells, add to your ~/.cshrc file the lines:: | ||
|
r1329 | setenv PAGER less | ||
|
r1258 | setenv LESS -r | ||
|
r2113 | |||
|
r1258 | 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:: | ||||
|
r1329 | (require 'ipython) | ||
|
r1258 | |||
This should give you full support for executing code snippets via | ||||
|
r1329 | IPython, opening IPython as your Python shell via ``C-c !``, etc. | ||
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")) | ||||
|
r1258 | |||
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:: | ||||
|
r1329 | (setq ansi-color-for-comint-mode t) | ||
|
r1258 | |||
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 | ||||
|
r1329 | customization variables comes later). | ||