This is an important trick for finding out configuration info:

$> ipython [subcommand] --help-all | grep [-C context] PATTERN

--help-all exposes everything configurable in IPython, there is a good chance you will find what you are looking for.

A common configuration question is:

how do I disable the "Do you really want to exit" message when quitting with Ctrl-d?

Well, logically this has to do with exit, so let's look for it:

In []:

!ipython --help-all | grep exit

Which shows me that I can disable the confirmation for a single IPython session with

$> ipython --no-confirm-exit

or I can set the TerminalInteractiveShell.confirm_exit=False in a config file, to have it be the default behavior.

Configuration principles¶

Here are the design principles of the IPython configuration system:

Configuration is always done using class attributes
Classes that have configurable attributes are subclasses of Configurable
Attributes that are configurable are typed traitlets objects (Bool, Unicode, etc.) that have config=True
In config files, configurable attributes can be set using the format Class.attr_name=the_value
At the command line, configurable attributes can be set using the syntax --Class.attr_name=the_value
At the command line, some attributes have shorthands of the form --attr-name=value
Values set at the command line have higher priority than those set in config files

The IPython Profile¶

IPython has a notion of 'profiles' - these are directories that live in your IPYTHONDIR, which contain configuration and runtime information.

Let's create the default profile

In []:

!ipython profile create

This creates a profile in your IPYTHONDIR (ipython locate is a quick way to see where your IPYTHONDIR is), and populates it with automatically generated default config files.

In []:

!ipython locate profile default

In []:

profile = get_ipython().profile_dir.location
profile

Let's peek at our config file

In []:

pycat $profile/ipython_config.py

The %config magic lets you do some configuration at runtime, rather than in configuration files.

In []:

%pylab inline

%config with no arguments will show you what configurable objects exist:

And %config Class will show you the config for that class:

In []:

%config InlineBackend

Most importantly, the %config magic can be used to change the value of a configurable attribute at runtime. Here we tell the inline matplotlib backend to use SVG instead of the default PNG

In []:

x = linspace(0,10,1000)
y = sin(x)
plot(x,sin(x))

In []:

%config InlineBackend.figure_format = 'svg'

In []:

plot(x,sin(x))

Defining your own magic¶

As we have seen already, IPython has cell and line magics. You can define your own magics using any Python function and the register_magic_function method:

In []:

ip = get_ipython()

In []:

def sleep_magic(line):
    """A simple function for sleeping"""
    t = float(line)
    import time
    time.sleep(t)

In []:

ip.register_magic_function(sleep_magic, "line", "sleep")

In []:

ip.magics_manager.define_magic?

Define %tic and %toc magics, which can be use for simple timings, e.g. where

for p in range(1,4):
    N = 10**p
    print "N=%i" % N
    %tic
    A = np.random.random((N,N))
    np.linalg.eigvals(A)
    %toc

each %toc will print the time since the last %tic. Create separate tic and toc functions that read and write a global time variable.

In []:

%load soln/tictocf.py

In []:

import time

def format_time(dt):
    if dt < 1e-6:
        return u"%.3g ns" % (dt * 1e9)
    elif dt < 1e-3:
        return u"%.3g µs" % (dt * 1e6)
    elif dt < 1:
        return u"%.3g ms" % (dt * 1e3)
    else:
        return "%.3g s" % dt

def tic(line):
    global t0
    t0 = time.time()

def toc(line):
    global t0
    print format_time(time.time() - t0)

ip = get_ipython()
ip.register_magic_function(tic)
ip.register_magic_function(toc)

In []:

import numpy as np

for p in range(1,4):
    N = 10**p
    print "N=%i" % N
    %tic
    A = np.random.random((N,N))
    np.linalg.eigvals(A)
    %toc

Startup files are simple Python or IPython scripts that are run whenever you start IPython. These are a useful way to do super common imports, or for building database connections to load on startup of a non-default profile.

We can use a startup file to ensure that our %tic/toc magics are always defined, every time we start IPython.

Configuring IPython¶

Finding configuration options¶

Configuration principles¶

The IPython Profile¶

The %config magic¶

Defining your own magic¶

Exercise¶

Startup files¶