|
|
.. _customization:
|
|
|
|
|
|
========================
|
|
|
Customization of IPython
|
|
|
========================
|
|
|
|
|
|
There are 2 ways to configure IPython - the old way of using ipythonrc
|
|
|
files (an INI-file like format), and the new way that involves editing
|
|
|
your ipy_user_conf.py. Both configuration systems work at the same
|
|
|
time, so you can set your options in both, but if you are hesitating
|
|
|
about which alternative to choose, we recommend the ipy_user_conf.py
|
|
|
approach, as it will give you more power and control in the long
|
|
|
run. However, there are few options such as pylab_import_all that can
|
|
|
only be specified in ipythonrc file or command line - the reason for
|
|
|
this is that they are needed before IPython has been started up, and
|
|
|
the IPApi object used in ipy_user_conf.py is not yet available at that
|
|
|
time. A hybrid approach of specifying a few options in ipythonrc and
|
|
|
doing the more advanced configuration in ipy_user_conf.py is also
|
|
|
possible.
|
|
|
|
|
|
.. _ipythonrc:
|
|
|
|
|
|
The ipythonrc approach
|
|
|
======================
|
|
|
|
|
|
As we've already mentioned, IPython reads a configuration file which can
|
|
|
be specified at the command line (-rcfile) or which by default is
|
|
|
assumed to be called ipythonrc. Such a file is looked for in the current
|
|
|
directory where IPython is started and then in your IPYTHONDIR, which
|
|
|
allows you to have local configuration files for specific projects. In
|
|
|
this section we will call these types of configuration files simply
|
|
|
rcfiles (short for resource configuration file).
|
|
|
|
|
|
The syntax of an rcfile is one of key-value pairs separated by
|
|
|
whitespace, one per line. Lines beginning with a # are ignored as
|
|
|
comments, but comments can not be put on lines with data (the parser is
|
|
|
fairly primitive). Note that these are not python files, and this is
|
|
|
deliberate, because it allows us to do some things which would be quite
|
|
|
tricky to implement if they were normal python files.
|
|
|
|
|
|
First, an rcfile can contain permanent default values for almost all command
|
|
|
line options (except things like -help or -Version). :ref:`This section
|
|
|
<command_line_options>` contains a description of all command-line
|
|
|
options. However, values you explicitly specify at the command line override
|
|
|
the values defined in the rcfile.
|
|
|
|
|
|
Besides command line option values, the rcfile can specify values for
|
|
|
certain extra special options which are not available at the command
|
|
|
line. These options are briefly described below.
|
|
|
|
|
|
Each of these options may appear as many times as you need it in the file.
|
|
|
|
|
|
* include <file1> <file2> ...: you can name other rcfiles you want
|
|
|
to recursively load up to 15 levels (don't use the <> brackets in
|
|
|
your names!). This feature allows you to define a 'base' rcfile
|
|
|
with general options and special-purpose files which can be loaded
|
|
|
only when needed with particular configuration options. To make
|
|
|
this more convenient, IPython accepts the -profile <name> option
|
|
|
(abbreviates to -p <name>) which tells it to look for an rcfile
|
|
|
named ipythonrc-<name>.
|
|
|
* import_mod <mod1> <mod2> ...: import modules with 'import
|
|
|
<mod1>,<mod2>,...'
|
|
|
* import_some <mod> <f1> <f2> ...: import functions with 'from
|
|
|
<mod> import <f1>,<f2>,...'
|
|
|
* import_all <mod1> <mod2> ...: for each module listed import
|
|
|
functions with ``from <mod> import *``.
|
|
|
* execute <python code>: give any single-line python code to be
|
|
|
executed.
|
|
|
* execfile <filename>: execute the python file given with an
|
|
|
'execfile(filename)' command. Username expansion is performed on
|
|
|
the given names. So if you need any amount of extra fancy
|
|
|
customization that won't fit in any of the above 'canned' options,
|
|
|
you can just put it in a separate python file and execute it.
|
|
|
* alias <alias_def>: this is equivalent to calling
|
|
|
'%alias <alias_def>' at the IPython command line. This way, from
|
|
|
within IPython you can do common system tasks without having to
|
|
|
exit it or use the ! escape. IPython isn't meant to be a shell
|
|
|
replacement, but it is often very useful to be able to do things
|
|
|
with files while testing code. This gives you the flexibility to
|
|
|
have within IPython any aliases you may be used to under your
|
|
|
normal system shell.
|
|
|
|
|
|
ipy_user_conf.py
|
|
|
================
|
|
|
|
|
|
There should be a simple template ipy_user_conf.py file in your
|
|
|
~/.ipython directory. It is a plain python module that is imported
|
|
|
during IPython startup, so you can do pretty much what you want there
|
|
|
- import modules, configure extensions, change options, define magic
|
|
|
commands, put variables and functions in the IPython namespace,
|
|
|
etc. You use the IPython extension api object, acquired by
|
|
|
IPython.ipapi.get() and documented in the "IPython extension API"
|
|
|
chapter, to interact with IPython. A sample ipy_user_conf.py is listed
|
|
|
below for reference::
|
|
|
|
|
|
# Most of your config files and extensions will probably start
|
|
|
# with this import
|
|
|
|
|
|
import IPython.ipapi
|
|
|
ip = IPython.ipapi.get()
|
|
|
|
|
|
# You probably want to uncomment this if you did %upgrade -nolegacy
|
|
|
# import ipy_defaults
|
|
|
|
|
|
import os
|
|
|
|
|
|
def main():
|
|
|
|
|
|
#ip.dbg.debugmode = True
|
|
|
ip.dbg.debug_stack()
|
|
|
|
|
|
# uncomment if you want to get ipython -p sh behaviour
|
|
|
# without having to use command line switches
|
|
|
import ipy_profile_sh
|
|
|
import jobctrl
|
|
|
|
|
|
# Configure your favourite editor?
|
|
|
# Good idea e.g. for %edit os.path.isfile
|
|
|
|
|
|
#import ipy_editors
|
|
|
|
|
|
# Choose one of these:
|
|
|
|
|
|
#ipy_editors.scite()
|
|
|
#ipy_editors.scite('c:/opt/scite/scite.exe')
|
|
|
#ipy_editors.komodo()
|
|
|
#ipy_editors.idle()
|
|
|
# ... or many others, try 'ipy_editors??' after import to see them
|
|
|
|
|
|
# Or roll your own:
|
|
|
#ipy_editors.install_editor("c:/opt/jed +$line $file")
|
|
|
|
|
|
|
|
|
o = ip.options
|
|
|
# An example on how to set options
|
|
|
#o.autocall = 1
|
|
|
o.system_verbose = 0
|
|
|
|
|
|
#import_all("os sys")
|
|
|
#execf('~/_ipython/ns.py')
|
|
|
|
|
|
|
|
|
# -- prompt
|
|
|
# A different, more compact set of prompts from the default ones, that
|
|
|
# always show your current location in the filesystem:
|
|
|
|
|
|
#o.prompt_in1 = r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Normal\n\C_Green|\#>'
|
|
|
#o.prompt_in2 = r'.\D: '
|
|
|
#o.prompt_out = r'[\#] '
|
|
|
|
|
|
# Try one of these color settings if you can't read the text easily
|
|
|
# autoexec is a list of IPython commands to execute on startup
|
|
|
#o.autoexec.append('%colors LightBG')
|
|
|
#o.autoexec.append('%colors NoColor')
|
|
|
o.autoexec.append('%colors Linux')
|
|
|
|
|
|
|
|
|
# some config helper functions you can use
|
|
|
def import_all(modules):
|
|
|
""" Usage: import_all("os sys") """
|
|
|
for m in modules.split():
|
|
|
ip.ex("from %s import *" % m)
|
|
|
|
|
|
def execf(fname):
|
|
|
""" Execute a file in user namespace """
|
|
|
ip.ex('execfile("%s")' % os.path.expanduser(fname))
|
|
|
|
|
|
main()
|
|
|
|
|
|
.. _Prompts:
|
|
|
|
|
|
Fine-tuning your prompt
|
|
|
=======================
|
|
|
|
|
|
IPython's prompts can be customized using a syntax similar to that of
|
|
|
the bash shell. Many of bash's escapes are supported, as well as a few
|
|
|
additional ones. We list them below::
|
|
|
|
|
|
\#
|
|
|
the prompt/history count number. This escape is automatically
|
|
|
wrapped in the coloring codes for the currently active color scheme.
|
|
|
\N
|
|
|
the 'naked' prompt/history count number: this is just the number
|
|
|
itself, without any coloring applied to it. This lets you produce
|
|
|
numbered prompts with your own colors.
|
|
|
\D
|
|
|
the prompt/history count, with the actual digits replaced by dots.
|
|
|
Used mainly in continuation prompts (prompt_in2)
|
|
|
\w
|
|
|
the current working directory
|
|
|
\W
|
|
|
the basename of current working directory
|
|
|
\Xn
|
|
|
where $n=0\ldots5.$ The current working directory, with $HOME
|
|
|
replaced by ~, and filtered out to contain only $n$ path elements
|
|
|
\Yn
|
|
|
Similar to \Xn, but with the $n+1$ element included if it is ~ (this
|
|
|
is similar to the behavior of the %cn escapes in tcsh)
|
|
|
\u
|
|
|
the username of the current user
|
|
|
\$
|
|
|
if the effective UID is 0, a #, otherwise a $
|
|
|
\h
|
|
|
the hostname up to the first '.'
|
|
|
\H
|
|
|
the hostname
|
|
|
\n
|
|
|
a newline
|
|
|
\r
|
|
|
a carriage return
|
|
|
\v
|
|
|
IPython version string
|
|
|
|
|
|
In addition to these, ANSI color escapes can be insterted into the
|
|
|
prompts, as \C_ColorName. The list of valid color names is: Black, Blue,
|
|
|
Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray,
|
|
|
LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White,
|
|
|
Yellow.
|
|
|
|
|
|
Finally, IPython supports the evaluation of arbitrary expressions in
|
|
|
your prompt string. The prompt strings are evaluated through the syntax
|
|
|
of PEP 215, but basically you can use $x.y to expand the value of x.y,
|
|
|
and for more complicated expressions you can use braces: ${foo()+x} will
|
|
|
call function foo and add to it the value of x, before putting the
|
|
|
result into your prompt. For example, using
|
|
|
prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: '
|
|
|
will print the result of the uptime command on each prompt (assuming the
|
|
|
commands module has been imported in your ipythonrc file).
|
|
|
|
|
|
|
|
|
Prompt examples
|
|
|
|
|
|
The following options in an ipythonrc file will give you IPython's
|
|
|
default prompts::
|
|
|
|
|
|
prompt_in1 'In [\#]:'
|
|
|
prompt_in2 ' .\D.:'
|
|
|
prompt_out 'Out[\#]:'
|
|
|
|
|
|
which look like this::
|
|
|
|
|
|
In [1]: 1+2
|
|
|
Out[1]: 3
|
|
|
|
|
|
In [2]: for i in (1,2,3):
|
|
|
...: print i,
|
|
|
...:
|
|
|
1 2 3
|
|
|
|
|
|
These will give you a very colorful prompt with path information::
|
|
|
|
|
|
#prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>'
|
|
|
prompt_in2 ' ..\D>'
|
|
|
prompt_out '<\#>'
|
|
|
|
|
|
which look like this::
|
|
|
|
|
|
fperez[~/ipython]1> 1+2
|
|
|
<1> 3
|
|
|
fperez[~/ipython]2> for i in (1,2,3):
|
|
|
...> print i,
|
|
|
...>
|
|
|
1 2 3
|
|
|
|
|
|
|
|
|
.. _Profiles:
|
|
|
|
|
|
IPython profiles
|
|
|
================
|
|
|
|
|
|
As we already mentioned, IPython supports the -profile command-line option (see
|
|
|
:ref:`here <command_line_options>`). A profile is nothing more than a
|
|
|
particular configuration file like your basic ipythonrc one, but with
|
|
|
particular customizations for a specific purpose. When you start IPython with
|
|
|
'ipython -profile <name>', it assumes that in your IPYTHONDIR there is a file
|
|
|
called ipythonrc-<name> or ipy_profile_<name>.py, and loads it instead of the
|
|
|
normal ipythonrc.
|
|
|
|
|
|
This system allows you to maintain multiple configurations which load
|
|
|
modules, set options, define functions, etc. suitable for different
|
|
|
tasks and activate them in a very simple manner. In order to avoid
|
|
|
having to repeat all of your basic options (common things that don't
|
|
|
change such as your color preferences, for example), any profile can
|
|
|
include another configuration file. The most common way to use profiles
|
|
|
is then to have each one include your basic ipythonrc file as a starting
|
|
|
point, and then add further customizations.
|
