|
|
.. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
|
|
|
You can adapt this file completely to your liking, but it should at least
|
|
|
contain the root 'toctree' directive.
|
|
|
|
|
|
=================
|
|
|
IPython reference
|
|
|
=================
|
|
|
|
|
|
.. contents::
|
|
|
|
|
|
.. _command_line_options:
|
|
|
|
|
|
Command-line usage
|
|
|
==================
|
|
|
|
|
|
You start IPython with the command::
|
|
|
|
|
|
$ ipython [options] files
|
|
|
|
|
|
If invoked with no options, it executes all the files listed in sequence
|
|
|
and drops you into the interpreter while still acknowledging any options
|
|
|
you may have set in your ipythonrc file. This behavior is different from
|
|
|
standard Python, which when called as python -i will only execute one
|
|
|
file and ignore your configuration setup.
|
|
|
|
|
|
Please note that some of the configuration options are not available at
|
|
|
the command line, simply because they are not practical here. Look into
|
|
|
your ipythonrc configuration file for details on those. This file
|
|
|
typically installed in the $HOME/.ipython directory. For Windows users,
|
|
|
$HOME resolves to C:\\Documents and Settings\\YourUserName in most
|
|
|
instances. In the rest of this text, we will refer to this directory as
|
|
|
IPYTHONDIR.
|
|
|
|
|
|
.. _Threading options:
|
|
|
|
|
|
|
|
|
Special Threading Options
|
|
|
-------------------------
|
|
|
|
|
|
The following special options are ONLY valid at the beginning of the
|
|
|
command line, and not later. This is because they control the initial-
|
|
|
ization of ipython itself, before the normal option-handling mechanism
|
|
|
is active.
|
|
|
|
|
|
-gthread, -qthread, -q4thread, -wthread, -pylab:
|
|
|
Only one of these can be given, and it can only be given as
|
|
|
the first option passed to IPython (it will have no effect in
|
|
|
any other position). They provide threading support for the
|
|
|
GTK, Qt (versions 3 and 4) and WXPython toolkits, and for the
|
|
|
matplotlib library.
|
|
|
|
|
|
With any of the first four options, IPython starts running a
|
|
|
separate thread for the graphical toolkit's operation, so that
|
|
|
you can open and control graphical elements from within an
|
|
|
IPython command line, without blocking. All four provide
|
|
|
essentially the same functionality, respectively for GTK, Qt3,
|
|
|
Qt4 and WXWidgets (via their Python interfaces).
|
|
|
|
|
|
Note that with -wthread, you can additionally use the
|
|
|
-wxversion option to request a specific version of wx to be
|
|
|
used. This requires that you have the wxversion Python module
|
|
|
installed, which is part of recent wxPython distributions.
|
|
|
|
|
|
If -pylab is given, IPython loads special support for the mat
|
|
|
plotlib library (http://matplotlib.sourceforge.net), allowing
|
|
|
interactive usage of any of its backends as defined in the
|
|
|
user's ~/.matplotlib/matplotlibrc file. It automatically
|
|
|
activates GTK, Qt or WX threading for IPyhton if the choice of
|
|
|
matplotlib backend requires it. It also modifies the %run
|
|
|
command to correctly execute (without blocking) any
|
|
|
matplotlib-based script which calls show() at the end.
|
|
|
|
|
|
-tk
|
|
|
The -g/q/q4/wthread options, and -pylab (if matplotlib is
|
|
|
configured to use GTK, Qt3, Qt4 or WX), will normally block Tk
|
|
|
graphical interfaces. This means that when either GTK, Qt or WX
|
|
|
threading is active, any attempt to open a Tk GUI will result in a
|
|
|
dead window, and possibly cause the Python interpreter to crash.
|
|
|
An extra option, -tk, is available to address this issue. It can
|
|
|
only be given as a second option after any of the above (-gthread,
|
|
|
-wthread or -pylab).
|
|
|
|
|
|
If -tk is given, IPython will try to coordinate Tk threading
|
|
|
with GTK, Qt or WX. This is however potentially unreliable, and
|
|
|
you will have to test on your platform and Python configuration to
|
|
|
determine whether it works for you. Debian users have reported
|
|
|
success, apparently due to the fact that Debian builds all of Tcl,
|
|
|
Tk, Tkinter and Python with pthreads support. Under other Linux
|
|
|
environments (such as Fedora Core 2/3), this option has caused
|
|
|
random crashes and lockups of the Python interpreter. Under other
|
|
|
operating systems (Mac OSX and Windows), you'll need to try it to
|
|
|
find out, since currently no user reports are available.
|
|
|
|
|
|
There is unfortunately no way for IPython to determine at run time
|
|
|
whether -tk will work reliably or not, so you will need to do some
|
|
|
experiments before relying on it for regular work.
|
|
|
|
|
|
|
|
|
|
|
|
Regular Options
|
|
|
---------------
|
|
|
|
|
|
After the above threading options have been given, regular options can
|
|
|
follow in any order. All options can be abbreviated to their shortest
|
|
|
non-ambiguous form and are case-sensitive. One or two dashes can be
|
|
|
used. Some options have an alternate short form, indicated after a ``|``.
|
|
|
|
|
|
Most options can also be set from your ipythonrc configuration file. See
|
|
|
the provided example for more details on what the options do. Options
|
|
|
given at the command line override the values set in the ipythonrc file.
|
|
|
|
|
|
All options with a [no] prepended can be specified in negated form
|
|
|
(-nooption instead of -option) to turn the feature off.
|
|
|
|
|
|
-help print a help message and exit.
|
|
|
|
|
|
-pylab
|
|
|
this can only be given as the first option passed to IPython
|
|
|
(it will have no effect in any other position). It adds
|
|
|
special support for the matplotlib library
|
|
|
(http://matplotlib.sourceforge.ne), allowing interactive usage
|
|
|
of any of its backends as defined in the user's .matplotlibrc
|
|
|
file. It automatically activates GTK or WX threading for
|
|
|
IPyhton if the choice of matplotlib backend requires it. It
|
|
|
also modifies the %run command to correctly execute (without
|
|
|
blocking) any matplotlib-based script which calls show() at
|
|
|
the end. See `Matplotlib support`_ for more details.
|
|
|
|
|
|
-autocall <val>
|
|
|
Make IPython automatically call any callable object even if you
|
|
|
didn't type explicit parentheses. For example, 'str 43' becomes
|
|
|
'str(43)' automatically. The value can be '0' to disable the feature,
|
|
|
'1' for smart autocall, where it is not applied if there are no more
|
|
|
arguments on the line, and '2' for full autocall, where all callable
|
|
|
objects are automatically called (even if no arguments are
|
|
|
present). The default is '1'.
|
|
|
|
|
|
-[no]autoindent
|
|
|
Turn automatic indentation on/off.
|
|
|
|
|
|
-[no]automagic
|
|
|
make magic commands automatic (without needing their first character
|
|
|
to be %). Type %magic at the IPython prompt for more information.
|
|
|
|
|
|
-[no]autoedit_syntax
|
|
|
When a syntax error occurs after editing a file, automatically
|
|
|
open the file to the trouble causing line for convenient
|
|
|
fixing.
|
|
|
|
|
|
-[no]banner Print the initial information banner (default on).
|
|
|
|
|
|
-c <command>
|
|
|
execute the given command string. This is similar to the -c
|
|
|
option in the normal Python interpreter.
|
|
|
|
|
|
-cache_size, cs <n>
|
|
|
size of the output cache (maximum number of entries to hold in
|
|
|
memory). The default is 1000, you can change it permanently in your
|
|
|
config file. Setting it to 0 completely disables the caching system,
|
|
|
and the minimum value accepted is 20 (if you provide a value less than
|
|
|
20, it is reset to 0 and a warning is issued) This limit is defined
|
|
|
because otherwise you'll spend more time re-flushing a too small cache
|
|
|
than working.
|
|
|
|
|
|
-classic, cl
|
|
|
Gives IPython a similar feel to the classic Python
|
|
|
prompt.
|
|
|
|
|
|
-colors <scheme>
|
|
|
Color scheme for prompts and exception reporting. Currently
|
|
|
implemented: NoColor, Linux and LightBG.
|
|
|
|
|
|
-[no]color_info
|
|
|
IPython can display information about objects via a set of functions,
|
|
|
and optionally can use colors for this, syntax highlighting source
|
|
|
code and various other elements. However, because this information is
|
|
|
passed through a pager (like 'less') and many pagers get confused with
|
|
|
color codes, this option is off by default. You can test it and turn
|
|
|
it on permanently in your ipythonrc file if it works for you. As a
|
|
|
reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
|
|
|
that in RedHat 7.2 doesn't.
|
|
|
|
|
|
Test it and turn it on permanently if it works with your
|
|
|
system. The magic function %color_info allows you to toggle this
|
|
|
interactively for testing.
|
|
|
|
|
|
-[no]debug
|
|
|
Show information about the loading process. Very useful to pin down
|
|
|
problems with your configuration files or to get details about
|
|
|
session restores.
|
|
|
|
|
|
-[no]deep_reload:
|
|
|
IPython can use the deep_reload module which reloads changes in
|
|
|
modules recursively (it replaces the reload() function, so you don't
|
|
|
need to change anything to use it). deep_reload() forces a full
|
|
|
reload of modules whose code may have changed, which the default
|
|
|
reload() function does not.
|
|
|
|
|
|
When deep_reload is off, IPython will use the normal reload(),
|
|
|
but deep_reload will still be available as dreload(). This
|
|
|
feature is off by default [which means that you have both
|
|
|
normal reload() and dreload()].
|
|
|
|
|
|
-editor <name>
|
|
|
Which editor to use with the %edit command. By default,
|
|
|
IPython will honor your EDITOR environment variable (if not
|
|
|
set, vi is the Unix default and notepad the Windows one).
|
|
|
Since this editor is invoked on the fly by IPython and is
|
|
|
meant for editing small code snippets, you may want to use a
|
|
|
small, lightweight editor here (in case your default EDITOR is
|
|
|
something like Emacs).
|
|
|
|
|
|
-ipythondir <name>
|
|
|
name of your IPython configuration directory IPYTHONDIR. This
|
|
|
can also be specified through the environment variable
|
|
|
IPYTHONDIR.
|
|
|
|
|
|
-log, l
|
|
|
generate a log file of all input. The file is named
|
|
|
ipython_log.py in your current directory (which prevents logs
|
|
|
from multiple IPython sessions from trampling each other). You
|
|
|
can use this to later restore a session by loading your
|
|
|
logfile as a file to be executed with option -logplay (see
|
|
|
below).
|
|
|
|
|
|
-logfile, lf <name> specify the name of your logfile.
|
|
|
|
|
|
-logplay, lp <name>
|
|
|
|
|
|
you can replay a previous log. For restoring a session as close as
|
|
|
possible to the state you left it in, use this option (don't just run
|
|
|
the logfile). With -logplay, IPython will try to reconstruct the
|
|
|
previous working environment in full, not just execute the commands in
|
|
|
the logfile.
|
|
|
|
|
|
When a session is restored, logging is automatically turned on
|
|
|
again with the name of the logfile it was invoked with (it is
|
|
|
read from the log header). So once you've turned logging on for
|
|
|
a session, you can quit IPython and reload it as many times as
|
|
|
you want and it will continue to log its history and restore
|
|
|
from the beginning every time.
|
|
|
|
|
|
Caveats: there are limitations in this option. The history
|
|
|
variables _i*,_* and _dh don't get restored properly. In the
|
|
|
future we will try to implement full session saving by writing
|
|
|
and retrieving a 'snapshot' of the memory state of IPython. But
|
|
|
our first attempts failed because of inherent limitations of
|
|
|
Python's Pickle module, so this may have to wait.
|
|
|
|
|
|
-[no]messages
|
|
|
Print messages which IPython collects about its startup
|
|
|
process (default on).
|
|
|
|
|
|
-[no]pdb
|
|
|
Automatically call the pdb debugger after every uncaught
|
|
|
exception. If you are used to debugging using pdb, this puts
|
|
|
you automatically inside of it after any call (either in
|
|
|
IPython or in code called by it) which triggers an exception
|
|
|
which goes uncaught.
|
|
|
|
|
|
-pydb
|
|
|
Makes IPython use the third party "pydb" package as debugger,
|
|
|
instead of pdb. Requires that pydb is installed.
|
|
|
|
|
|
-[no]pprint
|
|
|
ipython can optionally use the pprint (pretty printer) module
|
|
|
for displaying results. pprint tends to give a nicer display
|
|
|
of nested data structures. If you like it, you can turn it on
|
|
|
permanently in your config file (default off).
|
|
|
|
|
|
-profile, p <name>
|
|
|
|
|
|
assume that your config file is ipythonrc-<name> or
|
|
|
ipy_profile_<name>.py (looks in current dir first, then in
|
|
|
IPYTHONDIR). This is a quick way to keep and load multiple
|
|
|
config files for different tasks, especially if you use the
|
|
|
include option of config files. You can keep a basic
|
|
|
IPYTHONDIR/ipythonrc file and then have other 'profiles' which
|
|
|
include this one and load extra things for particular
|
|
|
tasks. For example:
|
|
|
|
|
|
1. $HOME/.ipython/ipythonrc : load basic things you always want.
|
|
|
2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
|
|
|
3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
|
|
|
|
|
|
Since it is possible to create an endless loop by having
|
|
|
circular file inclusions, IPython will stop if it reaches 15
|
|
|
recursive inclusions.
|
|
|
|
|
|
-prompt_in1, pi1 <string>
|
|
|
|
|
|
Specify the string used for input prompts. Note that if you are using
|
|
|
numbered prompts, the number is represented with a '\#' in the
|
|
|
string. Don't forget to quote strings with spaces embedded in
|
|
|
them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>`
|
|
|
discusses in detail all the available escapes to customize your
|
|
|
prompts.
|
|
|
|
|
|
-prompt_in2, pi2 <string>
|
|
|
Similar to the previous option, but used for the continuation
|
|
|
prompts. The special sequence '\D' is similar to '\#', but
|
|
|
with all digits replaced dots (so you can have your
|
|
|
continuation prompt aligned with your input prompt). Default:
|
|
|
' .\D.:' (note three spaces at the start for alignment with
|
|
|
'In [\#]').
|
|
|
|
|
|
-prompt_out,po <string>
|
|
|
String used for output prompts, also uses numbers like
|
|
|
prompt_in1. Default: 'Out[\#]:'
|
|
|
|
|
|
-quick start in bare bones mode (no config file loaded).
|
|
|
|
|
|
-rcfile <name>
|
|
|
name of your IPython resource configuration file. Normally
|
|
|
IPython loads ipythonrc (from current directory) or
|
|
|
IPYTHONDIR/ipythonrc.
|
|
|
|
|
|
If the loading of your config file fails, IPython starts with
|
|
|
a bare bones configuration (no modules loaded at all).
|
|
|
|
|
|
-[no]readline
|
|
|
use the readline library, which is needed to support name
|
|
|
completion and command history, among other things. It is
|
|
|
enabled by default, but may cause problems for users of
|
|
|
X/Emacs in Python comint or shell buffers.
|
|
|
|
|
|
Note that X/Emacs 'eterm' buffers (opened with M-x term) support
|
|
|
IPython's readline and syntax coloring fine, only 'emacs' (M-x
|
|
|
shell and C-c !) buffers do not.
|
|
|
|
|
|
-screen_length, sl <n>
|
|
|
number of lines of your screen. This is used to control
|
|
|
printing of very long strings. Strings longer than this number
|
|
|
of lines will be sent through a pager instead of directly
|
|
|
printed.
|
|
|
|
|
|
The default value for this is 0, which means IPython will
|
|
|
auto-detect your screen size every time it needs to print certain
|
|
|
potentially long strings (this doesn't change the behavior of the
|
|
|
'print' keyword, it's only triggered internally). If for some
|
|
|
reason this isn't working well (it needs curses support), specify
|
|
|
it yourself. Otherwise don't change the default.
|
|
|
|
|
|
-separate_in, si <string>
|
|
|
|
|
|
separator before input prompts.
|
|
|
Default: '\n'
|
|
|
|
|
|
-separate_out, so <string>
|
|
|
separator before output prompts.
|
|
|
Default: nothing.
|
|
|
|
|
|
-separate_out2, so2
|
|
|
separator after output prompts.
|
|
|
Default: nothing.
|
|
|
For these three options, use the value 0 to specify no separator.
|
|
|
|
|
|
-nosep
|
|
|
shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
|
|
|
0'. Simply removes all input/output separators.
|
|
|
|
|
|
-upgrade
|
|
|
allows you to upgrade your IPYTHONDIR configuration when you
|
|
|
install a new version of IPython. Since new versions may
|
|
|
include new command line options or example files, this copies
|
|
|
updated ipythonrc-type files. However, it backs up (with a
|
|
|
.old extension) all files which it overwrites so that you can
|
|
|
merge back any customizations you might have in your personal
|
|
|
files. Note that you should probably use %upgrade instead,
|
|
|
it's a safer alternative.
|
|
|
|
|
|
|
|
|
-Version print version information and exit.
|
|
|
|
|
|
-wxversion <string>
|
|
|
Select a specific version of wxPython (used in conjunction
|
|
|
with -wthread). Requires the wxversion module, part of recent
|
|
|
wxPython distributions
|
|
|
|
|
|
-xmode <modename>
|
|
|
|
|
|
Mode for exception reporting.
|
|
|
|
|
|
Valid modes: Plain, Context and Verbose.
|
|
|
|
|
|
* Plain: similar to python's normal traceback printing.
|
|
|
* Context: prints 5 lines of context source code around each
|
|
|
line in the traceback.
|
|
|
* Verbose: similar to Context, but additionally prints the
|
|
|
variables currently visible where the exception happened
|
|
|
(shortening their strings if too long). This can potentially be
|
|
|
very slow, if you happen to have a huge data structure whose
|
|
|
string representation is complex to compute. Your computer may
|
|
|
appear to freeze for a while with cpu usage at 100%. If this
|
|
|
occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
|
|
|
more than once).
|
|
|
|
|
|
Interactive use
|
|
|
===============
|
|
|
|
|
|
Warning: IPython relies on the existence of a global variable called
|
|
|
_ip which controls the shell itself. If you redefine _ip to anything,
|
|
|
bizarre behavior will quickly occur.
|
|
|
|
|
|
Other than the above warning, IPython is meant to work as a drop-in
|
|
|
replacement for the standard interactive interpreter. As such, any code
|
|
|
which is valid python should execute normally under IPython (cases where
|
|
|
this is not true should be reported as bugs). It does, however, offer
|
|
|
many features which are not available at a standard python prompt. What
|
|
|
follows is a list of these.
|
|
|
|
|
|
|
|
|
Caution for Windows users
|
|
|
-------------------------
|
|
|
|
|
|
Windows, unfortunately, uses the '\' character as a path
|
|
|
separator. This is a terrible choice, because '\' also represents the
|
|
|
escape character in most modern programming languages, including
|
|
|
Python. For this reason, using '/' character is recommended if you
|
|
|
have problems with ``\``. However, in Windows commands '/' flags
|
|
|
options, so you can not use it for the root directory. This means that
|
|
|
paths beginning at the root must be typed in a contrived manner like:
|
|
|
``%copy \opt/foo/bar.txt \tmp``
|
|
|
|
|
|
.. _magic:
|
|
|
|
|
|
Magic command system
|
|
|
--------------------
|
|
|
|
|
|
IPython will treat any line whose first character is a % as a special
|
|
|
call to a 'magic' function. These allow you to control the behavior of
|
|
|
IPython itself, plus a lot of system-type features. They are all
|
|
|
prefixed with a % character, but parameters are given without
|
|
|
parentheses or quotes.
|
|
|
|
|
|
Example: typing '%cd mydir' (without the quotes) changes you working
|
|
|
directory to 'mydir', if it exists.
|
|
|
|
|
|
If you have 'automagic' enabled (in your ipythonrc file, via the command
|
|
|
line option -automagic or with the %automagic function), you don't need
|
|
|
to type in the % explicitly. IPython will scan its internal list of
|
|
|
magic functions and call one if it exists. With automagic on you can
|
|
|
then just type 'cd mydir' to go to directory 'mydir'. The automagic
|
|
|
system has the lowest possible precedence in name searches, so defining
|
|
|
an identifier with the same name as an existing magic function will
|
|
|
shadow it for automagic use. You can still access the shadowed magic
|
|
|
function by explicitly using the % character at the beginning of the line.
|
|
|
|
|
|
An example (with automagic on) should clarify all this::
|
|
|
|
|
|
In [1]: cd ipython # %cd is called by automagic
|
|
|
|
|
|
/home/fperez/ipython
|
|
|
|
|
|
In [2]: cd=1 # now cd is just a variable
|
|
|
|
|
|
In [3]: cd .. # and doesn't work as a function anymore
|
|
|
|
|
|
------------------------------
|
|
|
|
|
|
File "<console>", line 1
|
|
|
|
|
|
cd ..
|
|
|
|
|
|
^
|
|
|
|
|
|
SyntaxError: invalid syntax
|
|
|
|
|
|
In [4]: %cd .. # but %cd always works
|
|
|
|
|
|
/home/fperez
|
|
|
|
|
|
In [5]: del cd # if you remove the cd variable
|
|
|
|
|
|
In [6]: cd ipython # automagic can work again
|
|
|
|
|
|
/home/fperez/ipython
|
|
|
|
|
|
You can define your own magic functions to extend the system. The
|
|
|
following example defines a new magic command, %impall::
|
|
|
|
|
|
import IPython.ipapi
|
|
|
|
|
|
ip = IPython.ipapi.get()
|
|
|
|
|
|
def doimp(self, arg):
|
|
|
|
|
|
ip = self.api
|
|
|
|
|
|
ip.ex("import %s; reload(%s); from %s import *" % (
|
|
|
|
|
|
arg,arg,arg)
|
|
|
|
|
|
)
|
|
|
|
|
|
ip.expose_magic('impall', doimp)
|
|
|
|
|
|
You can also define your own aliased names for magic functions. In your
|
|
|
ipythonrc file, placing a line like:
|
|
|
|
|
|
execute __IP.magic_cl = __IP.magic_clear
|
|
|
|
|
|
will define %cl as a new name for %clear.
|
|
|
|
|
|
Type %magic for more information, including a list of all available
|
|
|
magic functions at any time and their docstrings. You can also type
|
|
|
%magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
|
|
|
information on the '?' system) to get information about any particular
|
|
|
magic function you are interested in.
|
|
|
|
|
|
|
|
|
Magic commands
|
|
|
--------------
|
|
|
|
|
|
The rest of this section is automatically generated for each release
|
|
|
from the docstrings in the IPython code. Therefore the formatting is
|
|
|
somewhat minimal, but this method has the advantage of having
|
|
|
information always in sync with the code.
|
|
|
|
|
|
A list of all the magic commands available in IPython's default
|
|
|
installation follows. This is similar to what you'll see by simply
|
|
|
typing %magic at the prompt, but that will also give you information
|
|
|
about magic commands you may have added as part of your personal
|
|
|
customizations.
|
|
|
|
|
|
.. magic_start
|
|
|
|
|
|
**%Exit**::
|
|
|
|
|
|
Exit IPython without confirmation.
|
|
|
|
|
|
**%Pprint**::
|
|
|
|
|
|
Toggle pretty printing on/off.
|
|
|
|
|
|
**%alias**::
|
|
|
|
|
|
Define an alias for a system command.
|
|
|
|
|
|
'%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
|
|
|
|
|
|
Then, typing 'alias_name params' will execute the system command 'cmd
|
|
|
params' (from your underlying operating system).
|
|
|
|
|
|
Aliases have lower precedence than magic functions and Python normal
|
|
|
variables, so if 'foo' is both a Python variable and an alias, the
|
|
|
alias can not be executed until 'del foo' removes the Python variable.
|
|
|
|
|
|
You can use the %l specifier in an alias definition to represent the
|
|
|
whole line when the alias is called. For example:
|
|
|
|
|
|
In [2]: alias all echo "Input in brackets: <%l>"\
|
|
|
In [3]: all hello world\
|
|
|
Input in brackets: <hello world>
|
|
|
|
|
|
You can also define aliases with parameters using %s specifiers (one
|
|
|
per parameter):
|
|
|
|
|
|
In [1]: alias parts echo first %s second %s\
|
|
|
In [2]: %parts A B\
|
|
|
first A second B\
|
|
|
In [3]: %parts A\
|
|
|
Incorrect number of arguments: 2 expected.\
|
|
|
parts is an alias to: 'echo first %s second %s'
|
|
|
|
|
|
Note that %l and %s are mutually exclusive. You can only use one or
|
|
|
the other in your aliases.
|
|
|
|
|
|
Aliases expand Python variables just like system calls using ! or !!
|
|
|
do: all expressions prefixed with '$' get expanded. For details of
|
|
|
the semantic rules, see PEP-215:
|
|
|
http://www.python.org/peps/pep-0215.html. This is the library used by
|
|
|
IPython for variable expansion. If you want to access a true shell
|
|
|
variable, an extra $ is necessary to prevent its expansion by IPython:
|
|
|
|
|
|
In [6]: alias show echo\
|
|
|
In [7]: PATH='A Python string'\
|
|
|
In [8]: show $PATH\
|
|
|
A Python string\
|
|
|
In [9]: show $$PATH\
|
|
|
/usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
|
|
|
|
|
|
You can use the alias facility to acess all of $PATH. See the %rehash
|
|
|
and %rehashx functions, which automatically create aliases for the
|
|
|
contents of your $PATH.
|
|
|
|
|
|
If called with no parameters, %alias prints the current alias table.
|
|
|
|
|
|
**%autocall**::
|
|
|
|
|
|
Make functions callable without having to type parentheses.
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
%autocall [mode]
|
|
|
|
|
|
The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
|
|
|
value is toggled on and off (remembering the previous state).
|
|
|
|
|
|
In more detail, these values mean:
|
|
|
|
|
|
0 -> fully disabled
|
|
|
|
|
|
1 -> active, but do not apply if there are no arguments on the line.
|
|
|
|
|
|
In this mode, you get:
|
|
|
|
|
|
In [1]: callable
|
|
|
Out[1]: <built-in function callable>
|
|
|
|
|
|
In [2]: callable 'hello'
|
|
|
------> callable('hello')
|
|
|
Out[2]: False
|
|
|
|
|
|
2 -> Active always. Even if no arguments are present, the callable
|
|
|
object is called:
|
|
|
|
|
|
In [4]: callable
|
|
|
------> callable()
|
|
|
|
|
|
Note that even with autocall off, you can still use '/' at the start of
|
|
|
a line to treat the first argument on the command line as a function
|
|
|
and add parentheses to it:
|
|
|
|
|
|
In [8]: /str 43
|
|
|
------> str(43)
|
|
|
Out[8]: '43'
|
|
|
|
|
|
**%autoindent**::
|
|
|
|
|
|
Toggle autoindent on/off (if available).
|
|
|
|
|
|
**%automagic**::
|
|
|
|
|
|
Make magic functions callable without having to type the initial %.
|
|
|
|
|
|
Without argumentsl toggles on/off (when off, you must call it as
|
|
|
%automagic, of course). With arguments it sets the value, and you can
|
|
|
use any of (case insensitive):
|
|
|
|
|
|
- on,1,True: to activate
|
|
|
|
|
|
- off,0,False: to deactivate.
|
|
|
|
|
|
Note that magic functions have lowest priority, so if there's a
|
|
|
variable whose name collides with that of a magic fn, automagic won't
|
|
|
work for that function (you get the variable instead). However, if you
|
|
|
delete the variable (del var), the previously shadowed magic function
|
|
|
becomes visible to automagic again.
|
|
|
|
|
|
**%bg**::
|
|
|
|
|
|
Run a job in the background, in a separate thread.
|
|
|
|
|
|
For example,
|
|
|
|
|
|
%bg myfunc(x,y,z=1)
|
|
|
|
|
|
will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
|
|
|
execution starts, a message will be printed indicating the job
|
|
|
number. If your job number is 5, you can use
|
|
|
|
|
|
myvar = jobs.result(5) or myvar = jobs[5].result
|
|
|
|
|
|
to assign this result to variable 'myvar'.
|
|
|
|
|
|
IPython has a job manager, accessible via the 'jobs' object. You can
|
|
|
type jobs? to get more information about it, and use jobs.<TAB> to see
|
|
|
its attributes. All attributes not starting with an underscore are
|
|
|
meant for public use.
|
|
|
|
|
|
In particular, look at the jobs.new() method, which is used to create
|
|
|
new jobs. This magic %bg function is just a convenience wrapper
|
|
|
around jobs.new(), for expression-based jobs. If you want to create a
|
|
|
new job with an explicit function object and arguments, you must call
|
|
|
jobs.new() directly.
|
|
|
|
|
|
The jobs.new docstring also describes in detail several important
|
|
|
caveats associated with a thread-based model for background job
|
|
|
execution. Type jobs.new? for details.
|
|
|
|
|
|
You can check the status of all jobs with jobs.status().
|
|
|
|
|
|
The jobs variable is set by IPython into the Python builtin namespace.
|
|
|
If you ever declare a variable named 'jobs', you will shadow this
|
|
|
name. You can either delete your global jobs variable to regain
|
|
|
access to the job manager, or make a new name and assign it manually
|
|
|
to the manager (stored in IPython's namespace). For example, to
|
|
|
assign the job manager to the Jobs name, use:
|
|
|
|
|
|
Jobs = __builtins__.jobs
|
|
|
|
|
|
**%bookmark**::
|
|
|
|
|
|
Manage IPython's bookmark system.
|
|
|
|
|
|
%bookmark <name> - set bookmark to current dir
|
|
|
%bookmark <name> <dir> - set bookmark to <dir>
|
|
|
%bookmark -l - list all bookmarks
|
|
|
%bookmark -d <name> - remove bookmark
|
|
|
%bookmark -r - remove all bookmarks
|
|
|
|
|
|
You can later on access a bookmarked folder with:
|
|
|
%cd -b <name>
|
|
|
or simply '%cd <name>' if there is no directory called <name> AND
|
|
|
there is such a bookmark defined.
|
|
|
|
|
|
Your bookmarks persist through IPython sessions, but they are
|
|
|
associated with each profile.
|
|
|
|
|
|
**%cd**::
|
|
|
|
|
|
Change the current working directory.
|
|
|
|
|
|
This command automatically maintains an internal list of directories
|
|
|
you visit during your IPython session, in the variable _dh. The
|
|
|
command %dhist shows this history nicely formatted. You can also
|
|
|
do 'cd -<tab>' to see directory history conveniently.
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
cd 'dir': changes to directory 'dir'.
|
|
|
|
|
|
cd -: changes to the last visited directory.
|
|
|
|
|
|
cd -<n>: changes to the n-th directory in the directory history.
|
|
|
|
|
|
cd -b <bookmark_name>: jump to a bookmark set by %bookmark
|
|
|
(note: cd <bookmark_name> is enough if there is no
|
|
|
directory <bookmark_name>, but a bookmark with the name exists.)
|
|
|
'cd -b <tab>' allows you to tab-complete bookmark names.
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-q: quiet. Do not print the working directory after the cd command is
|
|
|
executed. By default IPython's cd command does print this directory,
|
|
|
since the default prompts do not display path information.
|
|
|
|
|
|
Note that !cd doesn't work for this purpose because the shell where
|
|
|
!command runs is immediately discarded after executing 'command'.
|
|
|
|
|
|
**%clear**::
|
|
|
|
|
|
Clear various data (e.g. stored history data)
|
|
|
|
|
|
%clear out - clear output history
|
|
|
%clear in - clear input history
|
|
|
%clear shadow_compress - Compresses shadow history (to speed up ipython)
|
|
|
%clear shadow_nuke - permanently erase all entries in shadow history
|
|
|
%clear dhist - clear dir history
|
|
|
|
|
|
**%color_info**::
|
|
|
|
|
|
Toggle color_info.
|
|
|
|
|
|
The color_info configuration parameter controls whether colors are
|
|
|
used for displaying object details (by things like %psource, %pfile or
|
|
|
the '?' system). This function toggles this value with each call.
|
|
|
|
|
|
Note that unless you have a fairly recent pager (less works better
|
|
|
than more) in your system, using colored object information displays
|
|
|
will not work properly. Test it and see.
|
|
|
|
|
|
**%colors**::
|
|
|
|
|
|
Switch color scheme for prompts, info system and exception handlers.
|
|
|
|
|
|
Currently implemented schemes: NoColor, Linux, LightBG.
|
|
|
|
|
|
Color scheme names are not case-sensitive.
|
|
|
|
|
|
**%cpaste**::
|
|
|
|
|
|
Allows you to paste & execute a pre-formatted code block from clipboard
|
|
|
|
|
|
You must terminate the block with '--' (two minus-signs) alone on the
|
|
|
line. You can also provide your own sentinel with '%paste -s %%' ('%%'
|
|
|
is the new sentinel for this operation)
|
|
|
|
|
|
The block is dedented prior to execution to enable execution of method
|
|
|
definitions. '>' and '+' characters at the beginning of a line are
|
|
|
ignored, to allow pasting directly from e-mails or diff files. The
|
|
|
executed block is also assigned to variable named 'pasted_block' for
|
|
|
later editing with '%edit pasted_block'.
|
|
|
|
|
|
You can also pass a variable name as an argument, e.g. '%cpaste foo'.
|
|
|
This assigns the pasted block to variable 'foo' as string, without
|
|
|
dedenting or executing it.
|
|
|
|
|
|
Do not be alarmed by garbled output on Windows (it's a readline bug).
|
|
|
Just press enter and type -- (and press enter again) and the block
|
|
|
will be what was just pasted.
|
|
|
|
|
|
IPython statements (magics, shell escapes) are not supported (yet).
|
|
|
|
|
|
**%debug**::
|
|
|
|
|
|
Activate the interactive debugger in post-mortem mode.
|
|
|
|
|
|
If an exception has just occurred, this lets you inspect its stack
|
|
|
frames interactively. Note that this will always work only on the last
|
|
|
traceback that occurred, so you must call this quickly after an
|
|
|
exception that you wish to inspect has fired, because if another one
|
|
|
occurs, it clobbers the previous one.
|
|
|
|
|
|
If you want IPython to automatically do this on every exception, see
|
|
|
the %pdb magic for more details.
|
|
|
|
|
|
**%dhist**::
|
|
|
|
|
|
Print your history of visited directories.
|
|
|
|
|
|
%dhist -> print full history\
|
|
|
%dhist n -> print last n entries only\
|
|
|
%dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
|
|
|
|
|
|
This history is automatically maintained by the %cd command, and
|
|
|
always available as the global list variable _dh. You can use %cd -<n>
|
|
|
to go to directory number <n>.
|
|
|
|
|
|
Note that most of time, you should view directory history by entering
|
|
|
cd -<TAB>.
|
|
|
|
|
|
**%dirs**::
|
|
|
|
|
|
Return the current directory stack.
|
|
|
|
|
|
**%doctest_mode**::
|
|
|
|
|
|
Toggle doctest mode on and off.
|
|
|
|
|
|
This mode allows you to toggle the prompt behavior between normal
|
|
|
IPython prompts and ones that are as similar to the default IPython
|
|
|
interpreter as possible.
|
|
|
|
|
|
It also supports the pasting of code snippets that have leading '>>>'
|
|
|
and '...' prompts in them. This means that you can paste doctests from
|
|
|
files or docstrings (even if they have leading whitespace), and the
|
|
|
code will execute correctly. You can then use '%history -tn' to see
|
|
|
the translated history without line numbers; this will give you the
|
|
|
input after removal of all the leading prompts and whitespace, which
|
|
|
can be pasted back into an editor.
|
|
|
|
|
|
With these features, you can switch into this mode easily whenever you
|
|
|
need to do testing and changes to doctests, without having to leave
|
|
|
your existing IPython session.
|
|
|
|
|
|
**%ed**::
|
|
|
|
|
|
Alias to %edit.
|
|
|
|
|
|
**%edit**::
|
|
|
|
|
|
Bring up an editor and execute the resulting code.
|
|
|
|
|
|
Usage:
|
|
|
%edit [options] [args]
|
|
|
|
|
|
%edit runs IPython's editor hook. The default version of this hook is
|
|
|
set to call the __IPYTHON__.rc.editor command. This is read from your
|
|
|
environment variable $EDITOR. If this isn't found, it will default to
|
|
|
vi under Linux/Unix and to notepad under Windows. See the end of this
|
|
|
docstring for how to change the editor hook.
|
|
|
|
|
|
You can also set the value of this editor via the command 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 typically don't set environment variables).
|
|
|
|
|
|
This command allows you to conveniently edit multi-line code right in
|
|
|
your IPython session.
|
|
|
|
|
|
If called without arguments, %edit opens up an empty editor with a
|
|
|
temporary file and will execute the contents of this file when you
|
|
|
close it (don't forget to save it!).
|
|
|
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-n <number>: open the editor at a specified line number. By default,
|
|
|
the IPython editor hook uses the unix syntax 'editor +N filename', but
|
|
|
you can configure this by providing your own modified hook if your
|
|
|
favorite editor supports line-number specifications with a different
|
|
|
syntax.
|
|
|
|
|
|
-p: this will call the editor with the same data as the previous time
|
|
|
it was used, regardless of how long ago (in your current session) it
|
|
|
was.
|
|
|
|
|
|
-r: use 'raw' input. This option only applies to input taken from the
|
|
|
user's history. By default, the 'processed' history is used, so that
|
|
|
magics are loaded in their transformed version to valid Python. If
|
|
|
this option is given, the raw input as typed as the command line is
|
|
|
used instead. When you exit the editor, it will be executed by
|
|
|
IPython's own processor.
|
|
|
|
|
|
-x: do not execute the edited code immediately upon exit. This is
|
|
|
mainly useful if you are editing programs which need to be called with
|
|
|
command line arguments, which you can then do using %run.
|
|
|
|
|
|
|
|
|
Arguments:
|
|
|
|
|
|
If arguments are given, the following possibilites exist:
|
|
|
|
|
|
- The arguments are numbers or pairs of colon-separated numbers (like
|
|
|
1 4:8 9). These are interpreted as lines of previous input to be
|
|
|
loaded into the editor. The syntax is the same of the %macro command.
|
|
|
|
|
|
- If the argument doesn't start with a number, it is evaluated as a
|
|
|
variable and its contents loaded into the editor. You can thus edit
|
|
|
any string which contains python code (including the result of
|
|
|
previous edits).
|
|
|
|
|
|
- If the argument is the name of an object (other than a string),
|
|
|
IPython will try to locate the file where it was defined and open the
|
|
|
editor at the point where it is defined. You can use `%edit function`
|
|
|
to load an editor exactly at the point where 'function' is defined,
|
|
|
edit it and have the file be executed automatically.
|
|
|
|
|
|
If the object is a macro (see %macro for details), this opens up your
|
|
|
specified editor with a temporary file containing the macro's data.
|
|
|
Upon exit, the macro is reloaded with the contents of the file.
|
|
|
|
|
|
Note: opening at an exact line is only supported under Unix, and some
|
|
|
editors (like kedit and gedit up to Gnome 2.8) do not understand the
|
|
|
'+NUMBER' parameter necessary for this feature. Good editors like
|
|
|
(X)Emacs, vi, jed, pico and joe all do.
|
|
|
|
|
|
- If the argument is not found as a variable, IPython will look for a
|
|
|
file with that name (adding .py if necessary) and load it into the
|
|
|
editor. It will execute its contents with execfile() when you exit,
|
|
|
loading any code in the file into your interactive namespace.
|
|
|
|
|
|
After executing your code, %edit will return as output the code you
|
|
|
typed in the editor (except when it was an existing file). This way
|
|
|
you can reload the code in further invocations of %edit as a variable,
|
|
|
via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
|
|
|
the output.
|
|
|
|
|
|
Note that %edit is also available through the alias %ed.
|
|
|
|
|
|
This is an example of creating a simple function inside the editor and
|
|
|
then modifying it. First, start up the editor:
|
|
|
|
|
|
In [1]: ed\
|
|
|
Editing... done. Executing edited code...\
|
|
|
Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n'
|
|
|
|
|
|
We can then call the function foo():
|
|
|
|
|
|
In [2]: foo()\
|
|
|
foo() was defined in an editing session
|
|
|
|
|
|
Now we edit foo. IPython automatically loads the editor with the
|
|
|
(temporary) file where foo() was previously defined:
|
|
|
|
|
|
In [3]: ed foo\
|
|
|
Editing... done. Executing edited code...
|
|
|
|
|
|
And if we call foo() again we get the modified version:
|
|
|
|
|
|
In [4]: foo()\
|
|
|
foo() has now been changed!
|
|
|
|
|
|
Here is an example of how to edit a code snippet successive
|
|
|
times. First we call the editor:
|
|
|
|
|
|
In [8]: ed\
|
|
|
Editing... done. Executing edited code...\
|
|
|
hello\
|
|
|
Out[8]: "print 'hello'\n"
|
|
|
|
|
|
Now we call it again with the previous output (stored in _):
|
|
|
|
|
|
In [9]: ed _\
|
|
|
Editing... done. Executing edited code...\
|
|
|
hello world\
|
|
|
Out[9]: "print 'hello world'\n"
|
|
|
|
|
|
Now we call it with the output #8 (stored in _8, also as Out[8]):
|
|
|
|
|
|
In [10]: ed _8\
|
|
|
Editing... done. Executing edited code...\
|
|
|
hello again\
|
|
|
Out[10]: "print 'hello again'\n"
|
|
|
|
|
|
|
|
|
Changing the default editor hook:
|
|
|
|
|
|
If you wish to write your own editor hook, you can put it in a
|
|
|
configuration file which you load at startup time. The default hook
|
|
|
is defined in the IPython.hooks module, and you can use that as a
|
|
|
starting example for further modifications. That file also has
|
|
|
general instructions on how to set a new hook for use once you've
|
|
|
defined it.
|
|
|
|
|
|
**%env**::
|
|
|
|
|
|
List environment variables.
|
|
|
|
|
|
**%exit**::
|
|
|
|
|
|
Exit IPython, confirming if configured to do so.
|
|
|
|
|
|
You can configure whether IPython asks for confirmation upon exit by
|
|
|
setting the confirm_exit flag in the ipythonrc file.
|
|
|
|
|
|
**%hist**::
|
|
|
|
|
|
Alternate name for %history.
|
|
|
|
|
|
**%history**::
|
|
|
|
|
|
Print input history (_i<n> variables), with most recent last.
|
|
|
|
|
|
%history -> print at most 40 inputs (some may be multi-line)\
|
|
|
%history n -> print at most n inputs\
|
|
|
%history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
|
|
|
|
|
|
Each input's number <n> is shown, and is accessible as the
|
|
|
automatically generated variable _i<n>. Multi-line statements are
|
|
|
printed starting at a new line for easy copy/paste.
|
|
|
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-n: do NOT print line numbers. This is useful if you want to get a
|
|
|
printout of many lines which can be directly pasted into a text
|
|
|
editor.
|
|
|
|
|
|
This feature is only available if numbered prompts are in use.
|
|
|
|
|
|
-t: (default) print the 'translated' history, as IPython understands it.
|
|
|
IPython filters your input and converts it all into valid Python source
|
|
|
before executing it (things like magics or aliases are turned into
|
|
|
function calls, for example). With this option, you'll see the native
|
|
|
history instead of the user-entered version: '%cd /' will be seen as
|
|
|
'_ip.magic("%cd /")' instead of '%cd /'.
|
|
|
|
|
|
-r: print the 'raw' history, i.e. the actual commands you typed.
|
|
|
|
|
|
-g: treat the arg as a pattern to grep for in (full) history.
|
|
|
This includes the "shadow history" (almost all commands ever written).
|
|
|
Use '%hist -g' to show full shadow history (may be very long).
|
|
|
In shadow history, every index nuwber starts with 0.
|
|
|
|
|
|
-f FILENAME: instead of printing the output to the screen, redirect it to
|
|
|
the given file. The file is always overwritten, though IPython asks for
|
|
|
confirmation first if it already exists.
|
|
|
|
|
|
**%logoff**::
|
|
|
|
|
|
Temporarily stop logging.
|
|
|
|
|
|
You must have previously started logging.
|
|
|
|
|
|
**%logon**::
|
|
|
|
|
|
Restart logging.
|
|
|
|
|
|
This function is for restarting logging which you've temporarily
|
|
|
stopped with %logoff. For starting logging for the first time, you
|
|
|
must use the %logstart function, which allows you to specify an
|
|
|
optional log filename.
|
|
|
|
|
|
**%logstart**::
|
|
|
|
|
|
Start logging anywhere in a session.
|
|
|
|
|
|
%logstart [-o|-r|-t] [log_name [log_mode]]
|
|
|
|
|
|
If no name is given, it defaults to a file named 'ipython_log.py' in your
|
|
|
current directory, in 'rotate' mode (see below).
|
|
|
|
|
|
'%logstart name' saves to file 'name' in 'backup' mode. It saves your
|
|
|
history up to that point and then continues logging.
|
|
|
|
|
|
%logstart takes a second optional parameter: logging mode. This can be one
|
|
|
of (note that the modes are given unquoted):\
|
|
|
append: well, that says it.\
|
|
|
backup: rename (if exists) to name~ and start name.\
|
|
|
global: single logfile in your home dir, appended to.\
|
|
|
over : overwrite existing log.\
|
|
|
rotate: create rotating logs name.1~, name.2~, etc.
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-o: log also IPython's output. In this mode, all commands which
|
|
|
generate an Out[NN] prompt are recorded to the logfile, right after
|
|
|
their corresponding input line. The output lines are always
|
|
|
prepended with a '#[Out]# ' marker, so that the log remains valid
|
|
|
Python code.
|
|
|
|
|
|
Since this marker is always the same, filtering only the output from
|
|
|
a log is very easy, using for example a simple awk call:
|
|
|
|
|
|
awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
|
|
|
|
|
|
-r: log 'raw' input. Normally, IPython's logs contain the processed
|
|
|
input, so that user lines are logged in their final form, converted
|
|
|
into valid Python. For example, %Exit is logged as
|
|
|
'_ip.magic("Exit"). If the -r flag is given, all input is logged
|
|
|
exactly as typed, with no transformations applied.
|
|
|
|
|
|
-t: put timestamps before each input line logged (these are put in
|
|
|
comments).
|
|
|
|
|
|
**%logstate**::
|
|
|
|
|
|
Print the status of the logging system.
|
|
|
|
|
|
**%logstop**::
|
|
|
|
|
|
Fully stop logging and close log file.
|
|
|
|
|
|
In order to start logging again, a new %logstart call needs to be made,
|
|
|
possibly (though not necessarily) with a new filename, mode and other
|
|
|
options.
|
|
|
|
|
|
**%lsmagic**::
|
|
|
|
|
|
List currently available magic functions.
|
|
|
|
|
|
**%macro**::
|
|
|
|
|
|
Define a set of input lines as a macro for future re-execution.
|
|
|
|
|
|
Usage:\
|
|
|
%macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-r: use 'raw' input. By default, the 'processed' history is used,
|
|
|
so that magics are loaded in their transformed version to valid
|
|
|
Python. If this option is given, the raw input as typed as the
|
|
|
command line is used instead.
|
|
|
|
|
|
This will define a global variable called `name` which is a string
|
|
|
made of joining the slices and lines you specify (n1,n2,... numbers
|
|
|
above) from your input history into a single string. This variable
|
|
|
acts like an automatic function which re-executes those lines as if
|
|
|
you had typed them. You just type 'name' at the prompt and the code
|
|
|
executes.
|
|
|
|
|
|
The notation for indicating number ranges is: n1-n2 means 'use line
|
|
|
numbers n1,...n2' (the endpoint is included). That is, '5-7' means
|
|
|
using the lines numbered 5,6 and 7.
|
|
|
|
|
|
Note: as a 'hidden' feature, you can also use traditional python slice
|
|
|
notation, where N:M means numbers N through M-1.
|
|
|
|
|
|
For example, if your history contains (%hist prints it):
|
|
|
|
|
|
44: x=1\
|
|
|
45: y=3\
|
|
|
46: z=x+y\
|
|
|
47: print x\
|
|
|
48: a=5\
|
|
|
49: print 'x',x,'y',y\
|
|
|
|
|
|
you can create a macro with lines 44 through 47 (included) and line 49
|
|
|
called my_macro with:
|
|
|
|
|
|
In [51]: %macro my_macro 44-47 49
|
|
|
|
|
|
Now, typing `my_macro` (without quotes) will re-execute all this code
|
|
|
in one pass.
|
|
|
|
|
|
You don't need to give the line-numbers in order, and any given line
|
|
|
number can appear multiple times. You can assemble macros with any
|
|
|
lines from your input history in any order.
|
|
|
|
|
|
The macro is a simple object which holds its value in an attribute,
|
|
|
but IPython's display system checks for macros and executes them as
|
|
|
code instead of printing them when you type their name.
|
|
|
|
|
|
You can view a macro's contents by explicitly printing it with:
|
|
|
|
|
|
'print macro_name'.
|
|
|
|
|
|
For one-off cases which DON'T contain magic function calls in them you
|
|
|
can obtain similar results by explicitly executing slices from your
|
|
|
input history with:
|
|
|
|
|
|
In [60]: exec In[44:48]+In[49]
|
|
|
|
|
|
**%magic**::
|
|
|
|
|
|
Print information about the magic function system.
|
|
|
|
|
|
**%mglob**::
|
|
|
|
|
|
This program allows specifying filenames with "mglob" mechanism.
|
|
|
Supported syntax in globs (wilcard matching patterns)::
|
|
|
|
|
|
*.cpp ?ellowo*
|
|
|
- obvious. Differs from normal glob in that dirs are not included.
|
|
|
Unix users might want to write this as: "*.cpp" "?ellowo*"
|
|
|
rec:/usr/share=*.txt,*.doc
|
|
|
- get all *.txt and *.doc under /usr/share,
|
|
|
recursively
|
|
|
rec:/usr/share
|
|
|
- All files under /usr/share, recursively
|
|
|
rec:*.py
|
|
|
- All .py files under current working dir, recursively
|
|
|
foo
|
|
|
- File or dir foo
|
|
|
!*.bak readme*
|
|
|
- readme*, exclude files ending with .bak
|
|
|
!.svn/ !.hg/ !*_Data/ rec:.
|
|
|
- Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
|
|
|
Trailing / is the key, \ does not work!
|
|
|
dir:foo
|
|
|
- the directory foo if it exists (not files in foo)
|
|
|
dir:*
|
|
|
- all directories in current folder
|
|
|
foo.py bar.* !h* rec:*.py
|
|
|
- Obvious. !h* exclusion only applies for rec:*.py.
|
|
|
foo.py is *not* included twice.
|
|
|
@filelist.txt
|
|
|
- All files listed in 'filelist.txt' file, on separate lines.
|
|
|
|
|
|
**%page**::
|
|
|
|
|
|
Pretty print the object and display it through a pager.
|
|
|
|
|
|
%page [options] OBJECT
|
|
|
|
|
|
If no object is given, use _ (last output).
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-r: page str(object), don't pretty-print it.
|
|
|
|
|
|
**%pdb**::
|
|
|
|
|
|
Control the automatic calling of the pdb interactive debugger.
|
|
|
|
|
|
Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
|
|
|
argument it works as a toggle.
|
|
|
|
|
|
When an exception is triggered, IPython can optionally call the
|
|
|
interactive pdb debugger after the traceback printout. %pdb toggles
|
|
|
this feature on and off.
|
|
|
|
|
|
The initial state of this feature is set in your ipythonrc
|
|
|
configuration file (the variable is called 'pdb').
|
|
|
|
|
|
If you want to just activate the debugger AFTER an exception has fired,
|
|
|
without having to type '%pdb on' and rerunning your code, you can use
|
|
|
the %debug magic.
|
|
|
|
|
|
**%pdef**::
|
|
|
|
|
|
Print the definition header for any callable object.
|
|
|
|
|
|
If the object is a class, print the constructor information.
|
|
|
|
|
|
**%pdoc**::
|
|
|
|
|
|
Print the docstring for an object.
|
|
|
|
|
|
If the given object is a class, it will print both the class and the
|
|
|
constructor docstrings.
|
|
|
|
|
|
**%pfile**::
|
|
|
|
|
|
Print (or run through pager) the file where an object is defined.
|
|
|
|
|
|
The file opens at the line where the object definition begins. IPython
|
|
|
will honor the environment variable PAGER if set, and otherwise will
|
|
|
do its best to print the file in a convenient form.
|
|
|
|
|
|
If the given argument is not an object currently defined, IPython will
|
|
|
try to interpret it as a filename (automatically adding a .py extension
|
|
|
if needed). You can thus use %pfile as a syntax highlighting code
|
|
|
viewer.
|
|
|
|
|
|
**%pinfo**::
|
|
|
|
|
|
Provide detailed information about an object.
|
|
|
|
|
|
'%pinfo object' is just a synonym for object? or ?object.
|
|
|
|
|
|
**%popd**::
|
|
|
|
|
|
Change to directory popped off the top of the stack.
|
|
|
|
|
|
**%profile**::
|
|
|
|
|
|
Print your currently active IPyhton profile.
|
|
|
|
|
|
**%prun**::
|
|
|
|
|
|
Run a statement through the python code profiler.
|
|
|
|
|
|
Usage:\
|
|
|
%prun [options] statement
|
|
|
|
|
|
The given statement (which doesn't require quote marks) is run via the
|
|
|
python profiler in a manner similar to the profile.run() function.
|
|
|
Namespaces are internally managed to work correctly; profile.run
|
|
|
cannot be used in IPython because it makes certain assumptions about
|
|
|
namespaces which do not hold under IPython.
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-l <limit>: you can place restrictions on what or how much of the
|
|
|
profile gets printed. The limit value can be:
|
|
|
|
|
|
* A string: only information for function names containing this string
|
|
|
is printed.
|
|
|
|
|
|
* An integer: only these many lines are printed.
|
|
|
|
|
|
* A float (between 0 and 1): this fraction of the report is printed
|
|
|
(for example, use a limit of 0.4 to see the topmost 40% only).
|
|
|
|
|
|
You can combine several limits with repeated use of the option. For
|
|
|
example, '-l __init__ -l 5' will print only the topmost 5 lines of
|
|
|
information about class constructors.
|
|
|
|
|
|
-r: return the pstats.Stats object generated by the profiling. This
|
|
|
object has all the information about the profile in it, and you can
|
|
|
later use it for further analysis or in other functions.
|
|
|
|
|
|
-s <key>: sort profile by given key. You can provide more than one key
|
|
|
by using the option several times: '-s key1 -s key2 -s key3...'. The
|
|
|
default sorting key is 'time'.
|
|
|
|
|
|
The following is copied verbatim from the profile documentation
|
|
|
referenced below:
|
|
|
|
|
|
When more than one key is provided, additional keys are used as
|
|
|
secondary criteria when the there is equality in all keys selected
|
|
|
before them.
|
|
|
|
|
|
Abbreviations can be used for any key names, as long as the
|
|
|
abbreviation is unambiguous. The following are the keys currently
|
|
|
defined:
|
|
|
|
|
|
Valid Arg Meaning\
|
|
|
"calls" call count\
|
|
|
"cumulative" cumulative time\
|
|
|
"file" file name\
|
|
|
"module" file name\
|
|
|
"pcalls" primitive call count\
|
|
|
"line" line number\
|
|
|
"name" function name\
|
|
|
"nfl" name/file/line\
|
|
|
"stdname" standard name\
|
|
|
"time" internal time
|
|
|
|
|
|
Note that all sorts on statistics are in descending order (placing
|
|
|
most time consuming items first), where as name, file, and line number
|
|
|
searches are in ascending order (i.e., alphabetical). The subtle
|
|
|
distinction between "nfl" and "stdname" is that the standard name is a
|
|
|
sort of the name as printed, which means that the embedded line
|
|
|
numbers get compared in an odd way. For example, lines 3, 20, and 40
|
|
|
would (if the file names were the same) appear in the string order
|
|
|
"20" "3" and "40". In contrast, "nfl" does a numeric compare of the
|
|
|
line numbers. In fact, sort_stats("nfl") is the same as
|
|
|
sort_stats("name", "file", "line").
|
|
|
|
|
|
-T <filename>: save profile results as shown on screen to a text
|
|
|
file. The profile is still shown on screen.
|
|
|
|
|
|
-D <filename>: save (via dump_stats) profile statistics to given
|
|
|
filename. This data is in a format understod by the pstats module, and
|
|
|
is generated by a call to the dump_stats() method of profile
|
|
|
objects. The profile is still shown on screen.
|
|
|
|
|
|
If you want to run complete programs under the profiler's control, use
|
|
|
'%run -p [prof_opts] filename.py [args to program]' where prof_opts
|
|
|
contains profiler specific options as described here.
|
|
|
|
|
|
You can read the complete documentation for the profile module with:\
|
|
|
In [1]: import profile; profile.help()
|
|
|
|
|
|
**%psearch**::
|
|
|
|
|
|
Search for object in namespaces by wildcard.
|
|
|
|
|
|
%psearch [options] PATTERN [OBJECT TYPE]
|
|
|
|
|
|
Note: ? can be used as a synonym for %psearch, at the beginning or at
|
|
|
the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
|
|
|
rest of the command line must be unchanged (options come first), so
|
|
|
for example the following forms are equivalent
|
|
|
|
|
|
%psearch -i a* function
|
|
|
-i a* function?
|
|
|
?-i a* function
|
|
|
|
|
|
Arguments:
|
|
|
|
|
|
PATTERN
|
|
|
|
|
|
where PATTERN is a string containing * as a wildcard similar to its
|
|
|
use in a shell. The pattern is matched in all namespaces on the
|
|
|
search path. By default objects starting with a single _ are not
|
|
|
matched, many IPython generated objects have a single
|
|
|
underscore. The default is case insensitive matching. Matching is
|
|
|
also done on the attributes of objects and not only on the objects
|
|
|
in a module.
|
|
|
|
|
|
[OBJECT TYPE]
|
|
|
|
|
|
Is the name of a python type from the types module. The name is
|
|
|
given in lowercase without the ending type, ex. StringType is
|
|
|
written string. By adding a type here only objects matching the
|
|
|
given type are matched. Using all here makes the pattern match all
|
|
|
types (this is the default).
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-a: makes the pattern match even objects whose names start with a
|
|
|
single underscore. These names are normally ommitted from the
|
|
|
search.
|
|
|
|
|
|
-i/-c: make the pattern case insensitive/sensitive. If neither of
|
|
|
these options is given, the default is read from your ipythonrc
|
|
|
file. The option name which sets this value is
|
|
|
'wildcards_case_sensitive'. If this option is not specified in your
|
|
|
ipythonrc file, IPython's internal default is to do a case sensitive
|
|
|
search.
|
|
|
|
|
|
-e/-s NAMESPACE: exclude/search a given namespace. The pattern you
|
|
|
specifiy can be searched in any of the following namespaces:
|
|
|
'builtin', 'user', 'user_global','internal', 'alias', where
|
|
|
'builtin' and 'user' are the search defaults. Note that you should
|
|
|
not use quotes when specifying namespaces.
|
|
|
|
|
|
'Builtin' contains the python module builtin, 'user' contains all
|
|
|
user data, 'alias' only contain the shell aliases and no python
|
|
|
objects, 'internal' contains objects used by IPython. The
|
|
|
'user_global' namespace is only used by embedded IPython instances,
|
|
|
and it contains module-level globals. You can add namespaces to the
|
|
|
search with -s or exclude them with -e (these options can be given
|
|
|
more than once).
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
%psearch a* -> objects beginning with an a
|
|
|
%psearch -e builtin a* -> objects NOT in the builtin space starting in a
|
|
|
%psearch a* function -> all functions beginning with an a
|
|
|
%psearch re.e* -> objects beginning with an e in module re
|
|
|
%psearch r*.e* -> objects that start with e in modules starting in r
|
|
|
%psearch r*.* string -> all strings in modules beginning with r
|
|
|
|
|
|
Case sensitve search:
|
|
|
|
|
|
%psearch -c a* list all object beginning with lower case a
|
|
|
|
|
|
Show objects beginning with a single _:
|
|
|
|
|
|
%psearch -a _* list objects beginning with a single underscore
|
|
|
|
|
|
**%psource**::
|
|
|
|
|
|
Print (or run through pager) the source code for an object.
|
|
|
|
|
|
**%pushd**::
|
|
|
|
|
|
Place the current dir on stack and change directory.
|
|
|
|
|
|
Usage:\
|
|
|
%pushd ['dirname']
|
|
|
|
|
|
**%pwd**::
|
|
|
|
|
|
Return the current working directory path.
|
|
|
|
|
|
**%pycat**::
|
|
|
|
|
|
Show a syntax-highlighted file through a pager.
|
|
|
|
|
|
This magic is similar to the cat utility, but it will assume the file
|
|
|
to be Python source and will show it with syntax highlighting.
|
|
|
|
|
|
**%quickref**::
|
|
|
|
|
|
Show a quick reference sheet
|
|
|
|
|
|
**%quit**::
|
|
|
|
|
|
Exit IPython, confirming if configured to do so (like %exit)
|
|
|
|
|
|
**%r**::
|
|
|
|
|
|
Repeat previous input.
|
|
|
|
|
|
Note: Consider using the more powerfull %rep instead!
|
|
|
|
|
|
If given an argument, repeats the previous command which starts with
|
|
|
the same string, otherwise it just repeats the previous input.
|
|
|
|
|
|
Shell escaped commands (with ! as first character) are not recognized
|
|
|
by this system, only pure python code and magic commands.
|
|
|
|
|
|
**%rehashdir**::
|
|
|
|
|
|
Add executables in all specified dirs to alias table
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
%rehashdir c:/bin;c:/tools
|
|
|
- Add all executables under c:/bin and c:/tools to alias table, in
|
|
|
order to make them directly executable from any directory.
|
|
|
|
|
|
Without arguments, add all executables in current directory.
|
|
|
|
|
|
**%rehashx**::
|
|
|
|
|
|
Update the alias table with all executable files in $PATH.
|
|
|
|
|
|
This version explicitly checks that every entry in $PATH is a file
|
|
|
with execute access (os.X_OK), so it is much slower than %rehash.
|
|
|
|
|
|
Under Windows, it checks executability as a match agains a
|
|
|
'|'-separated string of extensions, stored in the IPython config
|
|
|
variable win_exec_ext. This defaults to 'exe|com|bat'.
|
|
|
|
|
|
This function also resets the root module cache of module completer,
|
|
|
used on slow filesystems.
|
|
|
|
|
|
**%rep**::
|
|
|
|
|
|
Repeat a command, or get command to input line for editing
|
|
|
|
|
|
- %rep (no arguments):
|
|
|
|
|
|
Place a string version of last computation result (stored in the special '_'
|
|
|
variable) to the next input prompt. Allows you to create elaborate command
|
|
|
lines without using copy-paste::
|
|
|
|
|
|
$ l = ["hei", "vaan"]
|
|
|
$ "".join(l)
|
|
|
==> heivaan
|
|
|
$ %rep
|
|
|
$ heivaan_ <== cursor blinking
|
|
|
|
|
|
%rep 45
|
|
|
|
|
|
Place history line 45 to next input prompt. Use %hist to find out the
|
|
|
number.
|
|
|
|
|
|
%rep 1-4 6-7 3
|
|
|
|
|
|
Repeat the specified lines immediately. Input slice syntax is the same as
|
|
|
in %macro and %save.
|
|
|
|
|
|
%rep foo
|
|
|
|
|
|
Place the most recent line that has the substring "foo" to next input.
|
|
|
(e.g. 'svn ci -m foobar').
|
|
|
|
|
|
**%reset**::
|
|
|
|
|
|
Resets the namespace by removing all names defined by the user.
|
|
|
|
|
|
Input/Output history are left around in case you need them.
|
|
|
|
|
|
**%run**::
|
|
|
|
|
|
Run the named file inside IPython as a program.
|
|
|
|
|
|
Usage:\
|
|
|
%run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
|
|
|
|
|
|
Parameters after the filename are passed as command-line arguments to
|
|
|
the program (put in sys.argv). Then, control returns to IPython's
|
|
|
prompt.
|
|
|
|
|
|
This is similar to running at a system prompt:\
|
|
|
$ python file args\
|
|
|
but with the advantage of giving you IPython's tracebacks, and of
|
|
|
loading all variables into your interactive namespace for further use
|
|
|
(unless -p is used, see below).
|
|
|
|
|
|
The file is executed in a namespace initially consisting only of
|
|
|
__name__=='__main__' and sys.argv constructed as indicated. It thus
|
|
|
sees its environment as if it were being run as a stand-alone program
|
|
|
(except for sharing global objects such as previously imported
|
|
|
modules). But after execution, the IPython interactive namespace gets
|
|
|
updated with all variables defined in the program (except for __name__
|
|
|
and sys.argv). This allows for very convenient loading of code for
|
|
|
interactive work, while giving each program a 'clean sheet' to run in.
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-n: __name__ is NOT set to '__main__', but to the running file's name
|
|
|
without extension (as python does under import). This allows running
|
|
|
scripts and reloading the definitions in them without calling code
|
|
|
protected by an ' if __name__ == "__main__" ' clause.
|
|
|
|
|
|
-i: run the file in IPython's namespace instead of an empty one. This
|
|
|
is useful if you are experimenting with code written in a text editor
|
|
|
which depends on variables defined interactively.
|
|
|
|
|
|
-e: ignore sys.exit() calls or SystemExit exceptions in the script
|
|
|
being run. This is particularly useful if IPython is being used to
|
|
|
run unittests, which always exit with a sys.exit() call. In such
|
|
|
cases you are interested in the output of the test results, not in
|
|
|
seeing a traceback of the unittest module.
|
|
|
|
|
|
-t: print timing information at the end of the run. IPython will give
|
|
|
you an estimated CPU time consumption for your script, which under
|
|
|
Unix uses the resource module to avoid the wraparound problems of
|
|
|
time.clock(). Under Unix, an estimate of time spent on system tasks
|
|
|
is also given (for Windows platforms this is reported as 0.0).
|
|
|
|
|
|
If -t is given, an additional -N<N> option can be given, where <N>
|
|
|
must be an integer indicating how many times you want the script to
|
|
|
run. The final timing report will include total and per run results.
|
|
|
|
|
|
For example (testing the script uniq_stable.py):
|
|
|
|
|
|
In [1]: run -t uniq_stable
|
|
|
|
|
|
IPython CPU timings (estimated):\
|
|
|
User : 0.19597 s.\
|
|
|
System: 0.0 s.\
|
|
|
|
|
|
In [2]: run -t -N5 uniq_stable
|
|
|
|
|
|
IPython CPU timings (estimated):\
|
|
|
Total runs performed: 5\
|
|
|
Times : Total Per run\
|
|
|
User : 0.910862 s, 0.1821724 s.\
|
|
|
System: 0.0 s, 0.0 s.
|
|
|
|
|
|
-d: run your program under the control of pdb, the Python debugger.
|
|
|
This allows you to execute your program step by step, watch variables,
|
|
|
etc. Internally, what IPython does is similar to calling:
|
|
|
|
|
|
pdb.run('execfile("YOURFILENAME")')
|
|
|
|
|
|
with a breakpoint set on line 1 of your file. You can change the line
|
|
|
number for this automatic breakpoint to be <N> by using the -bN option
|
|
|
(where N must be an integer). For example:
|
|
|
|
|
|
%run -d -b40 myscript
|
|
|
|
|
|
will set the first breakpoint at line 40 in myscript.py. Note that
|
|
|
the first breakpoint must be set on a line which actually does
|
|
|
something (not a comment or docstring) for it to stop execution.
|
|
|
|
|
|
When the pdb debugger starts, you will see a (Pdb) prompt. You must
|
|
|
first enter 'c' (without qoutes) to start execution up to the first
|
|
|
breakpoint.
|
|
|
|
|
|
Entering 'help' gives information about the use of the debugger. You
|
|
|
can easily see pdb's full documentation with "import pdb;pdb.help()"
|
|
|
at a prompt.
|
|
|
|
|
|
-p: run program under the control of the Python profiler module (which
|
|
|
prints a detailed report of execution times, function calls, etc).
|
|
|
|
|
|
You can pass other options after -p which affect the behavior of the
|
|
|
profiler itself. See the docs for %prun for details.
|
|
|
|
|
|
In this mode, the program's variables do NOT propagate back to the
|
|
|
IPython interactive namespace (because they remain in the namespace
|
|
|
where the profiler executes them).
|
|
|
|
|
|
Internally this triggers a call to %prun, see its documentation for
|
|
|
details on the options available specifically for profiling.
|
|
|
|
|
|
There is one special usage for which the text above doesn't apply:
|
|
|
if the filename ends with .ipy, the file is run as ipython script,
|
|
|
just as if the commands were written on IPython prompt.
|
|
|
|
|
|
**%runlog**::
|
|
|
|
|
|
Run files as logs.
|
|
|
|
|
|
Usage:\
|
|
|
%runlog file1 file2 ...
|
|
|
|
|
|
Run the named files (treating them as log files) in sequence inside
|
|
|
the interpreter, and return to the prompt. This is much slower than
|
|
|
%run because each line is executed in a try/except block, but it
|
|
|
allows running files with syntax errors in them.
|
|
|
|
|
|
Normally IPython will guess when a file is one of its own logfiles, so
|
|
|
you can typically use %run even for logs. This shorthand allows you to
|
|
|
force any file to be treated as a log file.
|
|
|
|
|
|
**%save**::
|
|
|
|
|
|
Save a set of lines to a given filename.
|
|
|
|
|
|
Usage:\
|
|
|
%save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-r: use 'raw' input. By default, the 'processed' history is used,
|
|
|
so that magics are loaded in their transformed version to valid
|
|
|
Python. If this option is given, the raw input as typed as the
|
|
|
command line is used instead.
|
|
|
|
|
|
This function uses the same syntax as %macro for line extraction, but
|
|
|
instead of creating a macro it saves the resulting string to the
|
|
|
filename you specify.
|
|
|
|
|
|
It adds a '.py' extension to the file if you don't do so yourself, and
|
|
|
it asks for confirmation before overwriting existing files.
|
|
|
|
|
|
**%sc**::
|
|
|
|
|
|
Shell capture - execute a shell command and capture its output.
|
|
|
|
|
|
DEPRECATED. Suboptimal, retained for backwards compatibility.
|
|
|
|
|
|
You should use the form 'var = !command' instead. Example:
|
|
|
|
|
|
"%sc -l myfiles = ls ~" should now be written as
|
|
|
|
|
|
"myfiles = !ls ~"
|
|
|
|
|
|
myfiles.s, myfiles.l and myfiles.n still apply as documented
|
|
|
below.
|
|
|
|
|
|
--
|
|
|
%sc [options] varname=command
|
|
|
|
|
|
IPython will run the given command using commands.getoutput(), and
|
|
|
will then update the user's interactive namespace with a variable
|
|
|
called varname, containing the value of the call. Your command can
|
|
|
contain shell wildcards, pipes, etc.
|
|
|
|
|
|
The '=' sign in the syntax is mandatory, and the variable name you
|
|
|
supply must follow Python's standard conventions for valid names.
|
|
|
|
|
|
(A special format without variable name exists for internal use)
|
|
|
|
|
|
Options:
|
|
|
|
|
|
-l: list output. Split the output on newlines into a list before
|
|
|
assigning it to the given variable. By default the output is stored
|
|
|
as a single string.
|
|
|
|
|
|
-v: verbose. Print the contents of the variable.
|
|
|
|
|
|
In most cases you should not need to split as a list, because the
|
|
|
returned value is a special type of string which can automatically
|
|
|
provide its contents either as a list (split on newlines) or as a
|
|
|
space-separated string. These are convenient, respectively, either
|
|
|
for sequential processing or to be passed to a shell command.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
# Capture into variable a
|
|
|
In [9]: sc a=ls *py
|
|
|
|
|
|
# a is a string with embedded newlines
|
|
|
In [10]: a
|
|
|
Out[10]: 'setup.py win32_manual_post_install.py'
|
|
|
|
|
|
# which can be seen as a list:
|
|
|
In [11]: a.l
|
|
|
Out[11]: ['setup.py', 'win32_manual_post_install.py']
|
|
|
|
|
|
# or as a whitespace-separated string:
|
|
|
In [12]: a.s
|
|
|
Out[12]: 'setup.py win32_manual_post_install.py'
|
|
|
|
|
|
# a.s is useful to pass as a single command line:
|
|
|
In [13]: !wc -l $a.s
|
|
|
146 setup.py
|
|
|
130 win32_manual_post_install.py
|
|
|
276 total
|
|
|
|
|
|
# while the list form is useful to loop over:
|
|
|
In [14]: for f in a.l:
|
|
|
....: !wc -l $f
|
|
|
....:
|
|
|
146 setup.py
|
|
|
130 win32_manual_post_install.py
|
|
|
|
|
|
Similiarly, the lists returned by the -l option are also special, in
|
|
|
the sense that you can equally invoke the .s attribute on them to
|
|
|
automatically get a whitespace-separated string from their contents:
|
|
|
|
|
|
In [1]: sc -l b=ls *py
|
|
|
|
|
|
In [2]: b
|
|
|
Out[2]: ['setup.py', 'win32_manual_post_install.py']
|
|
|
|
|
|
In [3]: b.s
|
|
|
Out[3]: 'setup.py win32_manual_post_install.py'
|
|
|
|
|
|
In summary, both the lists and strings used for ouptut capture have
|
|
|
the following special attributes:
|
|
|
|
|
|
.l (or .list) : value as list.
|
|
|
.n (or .nlstr): value as newline-separated string.
|
|
|
.s (or .spstr): value as space-separated string.
|
|
|
|
|
|
**%store**::
|
|
|
|
|
|
Lightweight persistence for python variables.
|
|
|
|
|
|
Example:
|
|
|
|
|
|
ville@badger[~]|1> A = ['hello',10,'world']\
|
|
|
ville@badger[~]|2> %store A\
|
|
|
ville@badger[~]|3> Exit
|
|
|
|
|
|
(IPython session is closed and started again...)
|
|
|
|
|
|
ville@badger:~$ ipython -p pysh\
|
|
|
ville@badger[~]|1> print A
|
|
|
|
|
|
['hello', 10, 'world']
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
%store - Show list of all variables and their current values\
|
|
|
%store <var> - Store the *current* value of the variable to disk\
|
|
|
%store -d <var> - Remove the variable and its value from storage\
|
|
|
%store -z - Remove all variables from storage\
|
|
|
%store -r - Refresh all variables from store (delete current vals)\
|
|
|
%store foo >a.txt - Store value of foo to new file a.txt\
|
|
|
%store foo >>a.txt - Append value of foo to file a.txt\
|
|
|
|
|
|
It should be noted that if you change the value of a variable, you
|
|
|
need to %store it again if you want to persist the new value.
|
|
|
|
|
|
Note also that the variables will need to be pickleable; most basic
|
|
|
python types can be safely %stored.
|
|
|
|
|
|
Also aliases can be %store'd across sessions.
|
|
|
|
|
|
**%sx**::
|
|
|
|
|
|
Shell execute - run a shell command and capture its output.
|
|
|
|
|
|
%sx command
|
|
|
|
|
|
IPython will run the given command using commands.getoutput(), and
|
|
|
return the result formatted as a list (split on '\n'). Since the
|
|
|
output is _returned_, it will be stored in ipython's regular output
|
|
|
cache Out[N] and in the '_N' automatic variables.
|
|
|
|
|
|
Notes:
|
|
|
|
|
|
1) If an input line begins with '!!', then %sx is automatically
|
|
|
invoked. That is, while:
|
|
|
!ls
|
|
|
causes ipython to simply issue system('ls'), typing
|
|
|
!!ls
|
|
|
is a shorthand equivalent to:
|
|
|
%sx ls
|
|
|
|
|
|
2) %sx differs from %sc in that %sx automatically splits into a list,
|
|
|
like '%sc -l'. The reason for this is to make it as easy as possible
|
|
|
to process line-oriented shell output via further python commands.
|
|
|
%sc is meant to provide much finer control, but requires more
|
|
|
typing.
|
|
|
|
|
|
3) Just like %sc -l, this is a list with special attributes:
|
|
|
|
|
|
.l (or .list) : value as list.
|
|
|
.n (or .nlstr): value as newline-separated string.
|
|
|
.s (or .spstr): value as whitespace-separated string.
|
|
|
|
|
|
This is very useful when trying to use such lists as arguments to
|
|
|
system commands.
|
|
|
|
|
|
**%system_verbose**::
|
|
|
|
|
|
Set verbose printing of system calls.
|
|
|
|
|
|
If called without an argument, act as a toggle
|
|
|
|
|
|
**%time**::
|
|
|
|
|
|
Time execution of a Python statement or expression.
|
|
|
|
|
|
The CPU and wall clock times are printed, and the value of the
|
|
|
expression (if any) is returned. Note that under Win32, system time
|
|
|
is always reported as 0, since it can not be measured.
|
|
|
|
|
|
This function provides very basic timing functionality. In Python
|
|
|
2.3, the timeit module offers more control and sophistication, so this
|
|
|
could be rewritten to use it (patches welcome).
|
|
|
|
|
|
Some examples:
|
|
|
|
|
|
In [1]: time 2**128
|
|
|
CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
|
|
|
Wall time: 0.00
|
|
|
Out[1]: 340282366920938463463374607431768211456L
|
|
|
|
|
|
In [2]: n = 1000000
|
|
|
|
|
|
In [3]: time sum(range(n))
|
|
|
CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
|
|
|
Wall time: 1.37
|
|
|
Out[3]: 499999500000L
|
|
|
|
|
|
In [4]: time print 'hello world'
|
|
|
hello world
|
|
|
CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
|
|
|
Wall time: 0.00
|
|
|
|
|
|
Note that the time needed by Python to compile the given expression
|
|
|
will be reported if it is more than 0.1s. In this example, the
|
|
|
actual exponentiation is done by Python at compilation time, so while
|
|
|
the expression can take a noticeable amount of time to compute, that
|
|
|
time is purely due to the compilation:
|
|
|
|
|
|
In [5]: time 3**9999;
|
|
|
CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
|
|
|
Wall time: 0.00 s
|
|
|
|
|
|
In [6]: time 3**999999;
|
|
|
CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
|
|
|
Wall time: 0.00 s
|
|
|
Compiler : 0.78 s
|
|
|
|
|
|
**%timeit**::
|
|
|
|
|
|
Time execution of a Python statement or expression
|
|
|
|
|
|
Usage:\
|
|
|
%timeit [-n<N> -r<R> [-t|-c]] statement
|
|
|
|
|
|
Time execution of a Python statement or expression using the timeit
|
|
|
module.
|
|
|
|
|
|
Options:
|
|
|
-n<N>: execute the given statement <N> times in a loop. If this value
|
|
|
is not given, a fitting value is chosen.
|
|
|
|
|
|
-r<R>: repeat the loop iteration <R> times and take the best result.
|
|
|
Default: 3
|
|
|
|
|
|
-t: use time.time to measure the time, which is the default on Unix.
|
|
|
This function measures wall time.
|
|
|
|
|
|
-c: use time.clock to measure the time, which is the default on
|
|
|
Windows and measures wall time. On Unix, resource.getrusage is used
|
|
|
instead and returns the CPU user time.
|
|
|
|
|
|
-p<P>: use a precision of <P> digits to display the timing result.
|
|
|
Default: 3
|
|
|
|
|
|
|
|
|
Examples:\
|
|
|
In [1]: %timeit pass
|
|
|
10000000 loops, best of 3: 53.3 ns per loop
|
|
|
|
|
|
In [2]: u = None
|
|
|
|
|
|
In [3]: %timeit u is None
|
|
|
10000000 loops, best of 3: 184 ns per loop
|
|
|
|
|
|
In [4]: %timeit -r 4 u == None
|
|
|
1000000 loops, best of 4: 242 ns per loop
|
|
|
|
|
|
In [5]: import time
|
|
|
|
|
|
In [6]: %timeit -n1 time.sleep(2)
|
|
|
1 loops, best of 3: 2 s per loop
|
|
|
|
|
|
|
|
|
The times reported by %timeit will be slightly higher than those
|
|
|
reported by the timeit.py script when variables are accessed. This is
|
|
|
due to the fact that %timeit executes the statement in the namespace
|
|
|
of the shell, compared with timeit.py, which uses a single setup
|
|
|
statement to import function or create variables. Generally, the bias
|
|
|
does not matter as long as results from timeit.py are not mixed with
|
|
|
those from %timeit.
|
|
|
|
|
|
**%unalias**::
|
|
|
|
|
|
Remove an alias
|
|
|
|
|
|
**%upgrade**::
|
|
|
|
|
|
Upgrade your IPython installation
|
|
|
|
|
|
This will copy the config files that don't yet exist in your
|
|
|
ipython dir from the system config dir. Use this after upgrading
|
|
|
IPython if you don't wish to delete your .ipython dir.
|
|
|
|
|
|
Call with -nolegacy to get rid of ipythonrc* files (recommended for
|
|
|
new users)
|
|
|
|
|
|
**%which**::
|
|
|
|
|
|
%which <cmd> => search PATH for files matching cmd. Also scans aliases.
|
|
|
|
|
|
Traverses PATH and prints all files (not just executables!) that match the
|
|
|
pattern on command line. Probably more useful in finding stuff
|
|
|
interactively than 'which', which only prints the first matching item.
|
|
|
|
|
|
Also discovers and expands aliases, so you'll see what will be executed
|
|
|
when you call an alias.
|
|
|
|
|
|
Example:
|
|
|
|
|
|
[~]|62> %which d
|
|
|
d -> ls -F --color=auto
|
|
|
== c:\cygwin\bin\ls.exe
|
|
|
c:\cygwin\bin\d.exe
|
|
|
|
|
|
[~]|64> %which diff*
|
|
|
diff3 -> diff3
|
|
|
== c:\cygwin\bin\diff3.exe
|
|
|
diff -> diff
|
|
|
== c:\cygwin\bin\diff.exe
|
|
|
c:\cygwin\bin\diff.exe
|
|
|
c:\cygwin\bin\diff3.exe
|
|
|
|
|
|
**%who**::
|
|
|
|
|
|
Print all interactive variables, with some minimal formatting.
|
|
|
|
|
|
If any arguments are given, only variables whose type matches one of
|
|
|
these are printed. For example:
|
|
|
|
|
|
%who function str
|
|
|
|
|
|
will only list functions and strings, excluding all other types of
|
|
|
variables. To find the proper type names, simply use type(var) at a
|
|
|
command line to see how python prints type names. For example:
|
|
|
|
|
|
In [1]: type('hello')\
|
|
|
Out[1]: <type 'str'>
|
|
|
|
|
|
indicates that the type name for strings is 'str'.
|
|
|
|
|
|
%who always excludes executed names loaded through your configuration
|
|
|
file and things which are internal to IPython.
|
|
|
|
|
|
This is deliberate, as typically you may load many modules and the
|
|
|
purpose of %who is to show you only what you've manually defined.
|
|
|
|
|
|
**%who_ls**::
|
|
|
|
|
|
Return a sorted list of all interactive variables.
|
|
|
|
|
|
If arguments are given, only variables of types matching these
|
|
|
arguments are returned.
|
|
|
|
|
|
**%whos**::
|
|
|
|
|
|
Like %who, but gives some extra information about each variable.
|
|
|
|
|
|
The same type filtering of %who can be applied here.
|
|
|
|
|
|
For all variables, the type is printed. Additionally it prints:
|
|
|
|
|
|
- For {},[],(): their length.
|
|
|
|
|
|
- For numpy and Numeric arrays, a summary with shape, number of
|
|
|
elements, typecode and size in memory.
|
|
|
|
|
|
- Everything else: a string representation, snipping their middle if
|
|
|
too long.
|
|
|
|
|
|
**%xmode**::
|
|
|
|
|
|
Switch modes for the exception handlers.
|
|
|
|
|
|
Valid modes: Plain, Context and Verbose.
|
|
|
|
|
|
If called without arguments, acts as a toggle.
|
|
|
|
|
|
.. magic_end
|
|
|
|
|
|
Access to the standard Python help
|
|
|
----------------------------------
|
|
|
|
|
|
As of Python 2.1, a help system is available with access to object docstrings
|
|
|
and the Python manuals. Simply type 'help' (no quotes) to access it. You can
|
|
|
also type help(object) to obtain information about a given object, and
|
|
|
help('keyword') for information on a keyword. As noted :ref:`here
|
|
|
<accessing_help>`, you need to properly configure your environment variable
|
|
|
PYTHONDOCS for this feature to work correctly.
|
|
|
|
|
|
.. _dynamic_object_info:
|
|
|
|
|
|
Dynamic object information
|
|
|
--------------------------
|
|
|
|
|
|
Typing ?word or word? prints detailed information about an object. If
|
|
|
certain strings in the object are too long (docstrings, code, etc.) they
|
|
|
get snipped in the center for brevity. This system gives access variable
|
|
|
types and values, full source code for any object (if available),
|
|
|
function prototypes and other useful information.
|
|
|
|
|
|
Typing ??word or word?? gives access to the full information without
|
|
|
snipping long strings. Long strings are sent to the screen through the
|
|
|
less pager if longer than the screen and printed otherwise. On systems
|
|
|
lacking the less command, IPython uses a very basic internal pager.
|
|
|
|
|
|
The following magic functions are particularly useful for gathering
|
|
|
information about your working environment. You can get more details by
|
|
|
typing %magic or querying them individually (use %function_name? with or
|
|
|
without the %), this is just a summary:
|
|
|
|
|
|
* **%pdoc <object>**: Print (or run through a pager if too long) the
|
|
|
docstring for an object. If the given object is a class, it will
|
|
|
print both the class and the constructor docstrings.
|
|
|
* **%pdef <object>**: Print the definition header for any callable
|
|
|
object. If the object is a class, print the constructor information.
|
|
|
* **%psource <object>**: Print (or run through a pager if too long)
|
|
|
the source code for an object.
|
|
|
* **%pfile <object>**: Show the entire source file where an object was
|
|
|
defined via a pager, opening it at the line where the object
|
|
|
definition begins.
|
|
|
* **%who/%whos**: These functions give information about identifiers
|
|
|
you have defined interactively (not things you loaded or defined
|
|
|
in your configuration files). %who just prints a list of
|
|
|
identifiers and %whos prints a table with some basic details about
|
|
|
each identifier.
|
|
|
|
|
|
Note that the dynamic object information functions (?/??, %pdoc, %pfile,
|
|
|
%pdef, %psource) give you access to documentation even on things which
|
|
|
are not really defined as separate identifiers. Try for example typing
|
|
|
{}.get? or after doing import os, type os.path.abspath??.
|
|
|
|
|
|
|
|
|
.. _readline:
|
|
|
|
|
|
Readline-based features
|
|
|
-----------------------
|
|
|
|
|
|
These features require the GNU readline library, so they won't work if
|
|
|
your Python installation lacks readline support. We will first describe
|
|
|
the default behavior IPython uses, and then how to change it to suit
|
|
|
your preferences.
|
|
|
|
|
|
|
|
|
Command line completion
|
|
|
+++++++++++++++++++++++
|
|
|
|
|
|
At any time, hitting TAB will complete any available python commands or
|
|
|
variable names, and show you a list of the possible completions if
|
|
|
there's no unambiguous one. It will also complete filenames in the
|
|
|
current directory if no python names match what you've typed so far.
|
|
|
|
|
|
|
|
|
Search command history
|
|
|
++++++++++++++++++++++
|
|
|
|
|
|
IPython provides two ways for searching through previous input and thus
|
|
|
reduce the need for repetitive typing:
|
|
|
|
|
|
1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
|
|
|
(next,down) to search through only the history items that match
|
|
|
what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
|
|
|
prompt, they just behave like normal arrow keys.
|
|
|
2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
|
|
|
searches your history for lines that contain what you've typed so
|
|
|
far, completing as much as it can.
|
|
|
|
|
|
|
|
|
Persistent command history across sessions
|
|
|
++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
|
|
IPython will save your input history when it leaves and reload it next
|
|
|
time you restart it. By default, the history file is named
|
|
|
$IPYTHONDIR/history, but if you've loaded a named profile,
|
|
|
'-PROFILE_NAME' is appended to the name. This allows you to keep
|
|
|
separate histories related to various tasks: commands related to
|
|
|
numerical work will not be clobbered by a system shell history, for
|
|
|
example.
|
|
|
|
|
|
|
|
|
Autoindent
|
|
|
++++++++++
|
|
|
|
|
|
IPython can recognize lines ending in ':' and indent the next line,
|
|
|
while also un-indenting automatically after 'raise' or 'return'.
|
|
|
|
|
|
This feature uses the readline library, so it will honor your ~/.inputrc
|
|
|
configuration (or whatever file your INPUTRC variable points to). Adding
|
|
|
the following lines to your .inputrc file can make indenting/unindenting
|
|
|
more convenient (M-i indents, M-u unindents)::
|
|
|
|
|
|
$if Python
|
|
|
"\M-i": " "
|
|
|
"\M-u": "\d\d\d\d"
|
|
|
$endif
|
|
|
|
|
|
Note that there are 4 spaces between the quote marks after "M-i" above.
|
|
|
|
|
|
Warning: this feature is ON by default, but it can cause problems with
|
|
|
the pasting of multi-line indented code (the pasted code gets
|
|
|
re-indented on each line). A magic function %autoindent allows you to
|
|
|
toggle it on/off at runtime. You can also disable it permanently on in
|
|
|
your ipythonrc file (set autoindent 0).
|
|
|
|
|
|
|
|
|
Customizing readline behavior
|
|
|
+++++++++++++++++++++++++++++
|
|
|
|
|
|
All these features are based on the GNU readline library, which has an
|
|
|
extremely customizable interface. Normally, readline is configured via a
|
|
|
file which defines the behavior of the library; the details of the
|
|
|
syntax for this can be found in the readline documentation available
|
|
|
with your system or on the Internet. IPython doesn't read this file (if
|
|
|
it exists) directly, but it does support passing to readline valid
|
|
|
options via a simple interface. In brief, you can customize readline by
|
|
|
setting the following options in your ipythonrc configuration file (note
|
|
|
that these options can not be specified at the command line):
|
|
|
|
|
|
* **readline_parse_and_bind**: this option can appear as many times as
|
|
|
you want, each time defining a string to be executed via a
|
|
|
readline.parse_and_bind() command. The syntax for valid commands
|
|
|
of this kind can be found by reading the documentation for the GNU
|
|
|
readline library, as these commands are of the kind which readline
|
|
|
accepts in its configuration file.
|
|
|
* **readline_remove_delims**: a string of characters to be removed
|
|
|
from the default word-delimiters list used by readline, so that
|
|
|
completions may be performed on strings which contain them. Do not
|
|
|
change the default value unless you know what you're doing.
|
|
|
* **readline_omit__names**: when tab-completion is enabled, hitting
|
|
|
<tab> after a '.' in a name will complete all attributes of an
|
|
|
object, including all the special methods whose names include
|
|
|
double underscores (like __getitem__ or __class__). If you'd
|
|
|
rather not see these names by default, you can set this option to
|
|
|
1. Note that even when this option is set, you can still see those
|
|
|
names by explicitly typing a _ after the period and hitting <tab>:
|
|
|
'name._<tab>' will always complete attribute names starting with '_'.
|
|
|
|
|
|
This option is off by default so that new users see all
|
|
|
attributes of any objects they are dealing with.
|
|
|
|
|
|
You will find the default values along with a corresponding detailed
|
|
|
explanation in your ipythonrc file.
|
|
|
|
|
|
|
|
|
Session logging and restoring
|
|
|
-----------------------------
|
|
|
|
|
|
You can log all input from a session either by starting IPython with the
|
|
|
command line switches -log or -logfile (see :ref:`here <command_line_options>`)
|
|
|
or by activating the logging at any moment with the magic function %logstart.
|
|
|
|
|
|
Log files can later be reloaded with the -logplay option and IPython
|
|
|
will attempt to 'replay' the log by executing all the lines in it, thus
|
|
|
restoring the state of a previous session. This feature is not quite
|
|
|
perfect, but can still be useful in many cases.
|
|
|
|
|
|
The log files can also be used as a way to have a permanent record of
|
|
|
any code you wrote while experimenting. Log files are regular text files
|
|
|
which you can later open in your favorite text editor to extract code or
|
|
|
to 'clean them up' before using them to replay a session.
|
|
|
|
|
|
The %logstart function for activating logging in mid-session is used as
|
|
|
follows:
|
|
|
|
|
|
%logstart [log_name [log_mode]]
|
|
|
|
|
|
If no name is given, it defaults to a file named 'log' in your
|
|
|
IPYTHONDIR directory, in 'rotate' mode (see below).
|
|
|
|
|
|
'%logstart name' saves to file 'name' in 'backup' mode. It saves your
|
|
|
history up to that point and then continues logging.
|
|
|
|
|
|
%logstart takes a second optional parameter: logging mode. This can be
|
|
|
one of (note that the modes are given unquoted):
|
|
|
|
|
|
* [over:] overwrite existing log_name.
|
|
|
* [backup:] rename (if exists) to log_name~ and start log_name.
|
|
|
* [append:] well, that says it.
|
|
|
* [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
|
|
|
|
|
|
The %logoff and %logon functions allow you to temporarily stop and
|
|
|
resume logging to a file which had previously been started with
|
|
|
%logstart. They will fail (with an explanation) if you try to use them
|
|
|
before logging has been started.
|
|
|
|
|
|
.. _system_shell_access:
|
|
|
|
|
|
System shell access
|
|
|
-------------------
|
|
|
|
|
|
Any input line beginning with a ! character is passed verbatim (minus
|
|
|
the !, of course) to the underlying operating system. For example,
|
|
|
typing !ls will run 'ls' in the current directory.
|
|
|
|
|
|
Manual capture of command output
|
|
|
--------------------------------
|
|
|
|
|
|
If the input line begins with two exclamation marks, !!, the command is
|
|
|
executed but its output is captured and returned as a python list, split
|
|
|
on newlines. Any output sent by the subprocess to standard error is
|
|
|
printed separately, so that the resulting list only captures standard
|
|
|
output. The !! syntax is a shorthand for the %sx magic command.
|
|
|
|
|
|
Finally, the %sc magic (short for 'shell capture') is similar to %sx,
|
|
|
but allowing more fine-grained control of the capture details, and
|
|
|
storing the result directly into a named variable. The direct use of
|
|
|
%sc is now deprecated, and you should ise the ``var = !cmd`` syntax
|
|
|
instead.
|
|
|
|
|
|
IPython also allows you to expand the value of python variables when
|
|
|
making system calls. Any python variable or expression which you prepend
|
|
|
with $ will get expanded before the system call is made::
|
|
|
|
|
|
In [1]: pyvar='Hello world'
|
|
|
In [2]: !echo "A python variable: $pyvar"
|
|
|
A python variable: Hello world
|
|
|
|
|
|
If you want the shell to actually see a literal $, you need to type it
|
|
|
twice::
|
|
|
|
|
|
In [3]: !echo "A system variable: $$HOME"
|
|
|
A system variable: /home/fperez
|
|
|
|
|
|
You can pass arbitrary expressions, though you'll need to delimit them
|
|
|
with {} if there is ambiguity as to the extent of the expression::
|
|
|
|
|
|
In [5]: x=10
|
|
|
In [6]: y=20
|
|
|
In [13]: !echo $x+y
|
|
|
10+y
|
|
|
In [7]: !echo ${x+y}
|
|
|
30
|
|
|
|
|
|
Even object attributes can be expanded::
|
|
|
|
|
|
In [12]: !echo $sys.argv
|
|
|
[/home/fperez/usr/bin/ipython]
|
|
|
|
|
|
|
|
|
System command aliases
|
|
|
----------------------
|
|
|
|
|
|
The %alias magic function and the alias option in the ipythonrc
|
|
|
configuration file allow you to define magic functions which are in fact
|
|
|
system shell commands. These aliases can have parameters.
|
|
|
|
|
|
'%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
|
|
|
|
|
|
Then, typing '%alias_name params' will execute the system command 'cmd
|
|
|
params' (from your underlying operating system).
|
|
|
|
|
|
You can also define aliases with parameters using %s specifiers (one per
|
|
|
parameter). The following example defines the %parts function as an
|
|
|
alias to the command 'echo first %s second %s' where each %s will be
|
|
|
replaced by a positional parameter to the call to %parts::
|
|
|
|
|
|
In [1]: alias parts echo first %s second %s
|
|
|
In [2]: %parts A B
|
|
|
first A second B
|
|
|
In [3]: %parts A
|
|
|
Incorrect number of arguments: 2 expected.
|
|
|
parts is an alias to: 'echo first %s second %s'
|
|
|
|
|
|
If called with no parameters, %alias prints the table of currently
|
|
|
defined aliases.
|
|
|
|
|
|
The %rehash/rehashx magics allow you to load your entire $PATH as
|
|
|
ipython aliases. See their respective docstrings (or sec. 6.2
|
|
|
<#sec:magic> for further details).
|
|
|
|
|
|
|
|
|
.. _dreload:
|
|
|
|
|
|
Recursive reload
|
|
|
----------------
|
|
|
|
|
|
The dreload function does a recursive reload of a module: changes made
|
|
|
to the module since you imported will actually be available without
|
|
|
having to exit.
|
|
|
|
|
|
|
|
|
Verbose and colored exception traceback printouts
|
|
|
-------------------------------------------------
|
|
|
|
|
|
IPython provides the option to see very detailed exception tracebacks,
|
|
|
which can be especially useful when debugging large programs. You can
|
|
|
run any Python file with the %run function to benefit from these
|
|
|
detailed tracebacks. Furthermore, both normal and verbose tracebacks can
|
|
|
be colored (if your terminal supports it) which makes them much easier
|
|
|
to parse visually.
|
|
|
|
|
|
See the magic xmode and colors functions for details (just type %magic).
|
|
|
|
|
|
These features are basically a terminal version of Ka-Ping Yee's cgitb
|
|
|
module, now part of the standard Python library.
|
|
|
|
|
|
|
|
|
.. _input_caching:
|
|
|
|
|
|
Input caching system
|
|
|
--------------------
|
|
|
|
|
|
IPython offers numbered prompts (In/Out) with input and output caching.
|
|
|
All input is saved and can be retrieved as variables (besides the usual
|
|
|
arrow key recall).
|
|
|
|
|
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
|
_i: stores previous input. _ii: next previous. _iii: next-next previous.
|
|
|
_ih : a list of all input _ih[n] is the input from line n and this list
|
|
|
is aliased to the global variable In. If you overwrite In with a
|
|
|
variable of your own, you can remake the assignment to the internal list
|
|
|
with a simple 'In=_ih'.
|
|
|
|
|
|
Additionally, global variables named _i<n> are dynamically created (<n>
|
|
|
being the prompt counter), such that
|
|
|
_i<n> == _ih[<n>] == In[<n>].
|
|
|
|
|
|
For example, what you typed at prompt 14 is available as _i14, _ih[14]
|
|
|
and In[14].
|
|
|
|
|
|
This allows you to easily cut and paste multi line interactive prompts
|
|
|
by printing them out: they print like a clean string, without prompt
|
|
|
characters. You can also manipulate them like regular variables (they
|
|
|
are strings), modify or exec them (typing 'exec _i9' will re-execute the
|
|
|
contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
|
|
|
9 through 13 and line 18).
|
|
|
|
|
|
You can also re-execute multiple lines of input easily by using the
|
|
|
magic %macro function (which automates the process and allows
|
|
|
re-execution without having to type 'exec' every time). The macro system
|
|
|
also allows you to re-execute previous lines which include magic
|
|
|
function calls (which require special processing). Type %macro? or see
|
|
|
sec. 6.2 <#sec:magic> for more details on the macro system.
|
|
|
|
|
|
A history function %hist allows you to see any part of your input
|
|
|
history by printing a range of the _i variables.
|
|
|
|
|
|
.. _output_caching:
|
|
|
|
|
|
Output caching system
|
|
|
---------------------
|
|
|
|
|
|
For output that is returned from actions, a system similar to the input
|
|
|
cache exists but using _ instead of _i. Only actions that produce a
|
|
|
result (NOT assignments, for example) are cached. If you are familiar
|
|
|
with Mathematica, IPython's _ variables behave exactly like
|
|
|
Mathematica's % variables.
|
|
|
|
|
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
|
|
|
|
* [_] (a single underscore) : stores previous output, like Python's
|
|
|
default interpreter.
|
|
|
* [__] (two underscores): next previous.
|
|
|
* [___] (three underscores): next-next previous.
|
|
|
|
|
|
Additionally, global variables named _<n> are dynamically created (<n>
|
|
|
being the prompt counter), such that the result of output <n> is always
|
|
|
available as _<n> (don't use the angle brackets, just the number, e.g.
|
|
|
_21).
|
|
|
|
|
|
These global variables are all stored in a global dictionary (not a
|
|
|
list, since it only has entries for lines which returned a result)
|
|
|
available under the names _oh and Out (similar to _ih and In). So the
|
|
|
output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
|
|
|
accidentally overwrite the Out variable you can recover it by typing
|
|
|
'Out=_oh' at the prompt.
|
|
|
|
|
|
This system obviously can potentially put heavy memory demands on your
|
|
|
system, since it prevents Python's garbage collector from removing any
|
|
|
previously computed results. You can control how many results are kept
|
|
|
in memory with the option (at the command line or in your ipythonrc
|
|
|
file) cache_size. If you set it to 0, the whole system is completely
|
|
|
disabled and the prompts revert to the classic '>>>' of normal Python.
|
|
|
|
|
|
|
|
|
Directory history
|
|
|
-----------------
|
|
|
|
|
|
Your history of visited directories is kept in the global list _dh, and
|
|
|
the magic %cd command can be used to go to any entry in that list. The
|
|
|
%dhist command allows you to view this history. do ``cd -<TAB`` to
|
|
|
conventiently view the directory history.
|
|
|
|
|
|
|
|
|
Automatic parentheses and quotes
|
|
|
--------------------------------
|
|
|
|
|
|
These features were adapted from Nathan Gray's LazyPython. They are
|
|
|
meant to allow less typing for common situations.
|
|
|
|
|
|
|
|
|
Automatic parentheses
|
|
|
---------------------
|
|
|
|
|
|
Callable objects (i.e. functions, methods, etc) can be invoked like this
|
|
|
(notice the commas between the arguments)::
|
|
|
|
|
|
>>> callable_ob arg1, arg2, arg3
|
|
|
|
|
|
and the input will be translated to this::
|
|
|
|
|
|
-> callable_ob(arg1, arg2, arg3)
|
|
|
|
|
|
You can force automatic parentheses by using '/' as the first character
|
|
|
of a line. For example::
|
|
|
|
|
|
>>> /globals # becomes 'globals()'
|
|
|
|
|
|
Note that the '/' MUST be the first character on the line! This won't work::
|
|
|
|
|
|
>>> print /globals # syntax error
|
|
|
|
|
|
In most cases the automatic algorithm should work, so you should rarely
|
|
|
need to explicitly invoke /. One notable exception is if you are trying
|
|
|
to call a function with a list of tuples as arguments (the parenthesis
|
|
|
will confuse IPython)::
|
|
|
|
|
|
In [1]: zip (1,2,3),(4,5,6) # won't work
|
|
|
|
|
|
but this will work::
|
|
|
|
|
|
In [2]: /zip (1,2,3),(4,5,6)
|
|
|
---> zip ((1,2,3),(4,5,6))
|
|
|
Out[2]= [(1, 4), (2, 5), (3, 6)]
|
|
|
|
|
|
IPython tells you that it has altered your command line by displaying
|
|
|
the new command line preceded by ->. e.g.::
|
|
|
|
|
|
In [18]: callable list
|
|
|
----> callable (list)
|
|
|
|
|
|
|
|
|
Automatic quoting
|
|
|
-----------------
|
|
|
|
|
|
You can force automatic quoting of a function's arguments by using ','
|
|
|
or ';' as the first character of a line. For example::
|
|
|
|
|
|
>>> ,my_function /home/me # becomes my_function("/home/me")
|
|
|
|
|
|
If you use ';' instead, the whole argument is quoted as a single string
|
|
|
(while ',' splits on whitespace)::
|
|
|
|
|
|
>>> ,my_function a b c # becomes my_function("a","b","c")
|
|
|
|
|
|
>>> ;my_function a b c # becomes my_function("a b c")
|
|
|
|
|
|
Note that the ',' or ';' MUST be the first character on the line! This
|
|
|
won't work::
|
|
|
|
|
|
>>> x = ,my_function /home/me # syntax error
|
|
|
|
|
|
IPython as your default Python environment
|
|
|
==========================================
|
|
|
|
|
|
Python honors the environment variable PYTHONSTARTUP and will execute at
|
|
|
startup the file referenced by this variable. If you put at the end of
|
|
|
this file the following two lines of code::
|
|
|
|
|
|
import IPython
|
|
|
IPython.Shell.IPShell().mainloop(sys_exit=1)
|
|
|
|
|
|
then IPython will be your working environment anytime you start Python.
|
|
|
The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
|
|
|
it finishes, otherwise you'll be back at the normal Python '>>>'
|
|
|
prompt.
|
|
|
|
|
|
This is probably useful to developers who manage multiple Python
|
|
|
versions and don't want to have correspondingly multiple IPython
|
|
|
versions. Note that in this mode, there is no way to pass IPython any
|
|
|
command-line options, as those are trapped first by Python itself.
|
|
|
|
|
|
.. _Embedding:
|
|
|
|
|
|
Embedding IPython
|
|
|
=================
|
|
|
|
|
|
It is possible to start an IPython instance inside your own Python
|
|
|
programs. This allows you to evaluate dynamically the state of your
|
|
|
code, operate with your variables, analyze them, etc. Note however that
|
|
|
any changes you make to values while in the shell do not propagate back
|
|
|
to the running code, so it is safe to modify your values because you
|
|
|
won't break your code in bizarre ways by doing so.
|
|
|
|
|
|
This feature allows you to easily have a fully functional python
|
|
|
environment for doing object introspection anywhere in your code with a
|
|
|
simple function call. In some cases a simple print statement is enough,
|
|
|
but if you need to do more detailed analysis of a code fragment this
|
|
|
feature can be very valuable.
|
|
|
|
|
|
It can also be useful in scientific computing situations where it is
|
|
|
common to need to do some automatic, computationally intensive part and
|
|
|
then stop to look at data, plots, etc.
|
|
|
Opening an IPython instance will give you full access to your data and
|
|
|
functions, and you can resume program execution once you are done with
|
|
|
the interactive part (perhaps to stop again later, as many times as
|
|
|
needed).
|
|
|
|
|
|
The following code snippet is the bare minimum you need to include in
|
|
|
your Python programs for this to work (detailed examples follow later)::
|
|
|
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
|
|
|
ipshell = IPShellEmbed()
|
|
|
|
|
|
ipshell() # this call anywhere in your program will start IPython
|
|
|
|
|
|
You can run embedded instances even in code which is itself being run at
|
|
|
the IPython interactive prompt with '%run <filename>'. Since it's easy
|
|
|
to get lost as to where you are (in your top-level IPython or in your
|
|
|
embedded one), it's a good idea in such cases to set the in/out prompts
|
|
|
to something different for the embedded instances. The code examples
|
|
|
below illustrate this.
|
|
|
|
|
|
You can also have multiple IPython instances in your program and open
|
|
|
them separately, for example with different options for data
|
|
|
presentation. If you close and open the same instance multiple times,
|
|
|
its prompt counters simply continue from each execution to the next.
|
|
|
|
|
|
Please look at the docstrings in the Shell.py module for more details on
|
|
|
the use of this system.
|
|
|
|
|
|
The following sample file illustrating how to use the embedding
|
|
|
functionality is provided in the examples directory as example-embed.py.
|
|
|
It should be fairly self-explanatory::
|
|
|
|
|
|
|
|
|
#!/usr/bin/env python
|
|
|
|
|
|
"""An example of how to embed an IPython shell into a running program.
|
|
|
|
|
|
Please see the documentation in the IPython.Shell module for more details.
|
|
|
|
|
|
The accompanying file example-embed-short.py has quick code fragments for
|
|
|
embedding which you can cut and paste in your code once you understand how
|
|
|
things work.
|
|
|
|
|
|
The code in this file is deliberately extra-verbose, meant for learning."""
|
|
|
|
|
|
# The basics to get you going:
|
|
|
|
|
|
# IPython sets the __IPYTHON__ variable so you can know if you have nested
|
|
|
# copies running.
|
|
|
|
|
|
# Try running this code both at the command line and from inside IPython (with
|
|
|
# %run example-embed.py)
|
|
|
try:
|
|
|
__IPYTHON__
|
|
|
except NameError:
|
|
|
nested = 0
|
|
|
args = ['']
|
|
|
else:
|
|
|
print "Running nested copies of IPython."
|
|
|
print "The prompts for the nested copy have been modified"
|
|
|
nested = 1
|
|
|
# what the embedded instance will see as sys.argv:
|
|
|
args = ['-pi1','In <\\#>: ','-pi2',' .\\D.: ',
|
|
|
'-po','Out<\\#>: ','-nosep']
|
|
|
|
|
|
# First import the embeddable shell class
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
|
|
|
# Now create an instance of the embeddable shell. The first argument is a
|
|
|
# string with options exactly as you would type them if you were starting
|
|
|
# IPython at the system command line. Any parameters you want to define for
|
|
|
# configuration can thus be specified here.
|
|
|
ipshell = IPShellEmbed(args,
|
|
|
banner = 'Dropping into IPython',
|
|
|
exit_msg = 'Leaving Interpreter, back to program.')
|
|
|
|
|
|
# Make a second instance, you can have as many as you want.
|
|
|
if nested:
|
|
|
args[1] = 'In2<\\#>'
|
|
|
else:
|
|
|
args = ['-pi1','In2<\\#>: ','-pi2',' .\\D.: ',
|
|
|
'-po','Out<\\#>: ','-nosep']
|
|
|
ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
|
|
|
|
|
|
print '\nHello. This is printed from the main controller program.\n'
|
|
|
|
|
|
# You can then call ipshell() anywhere you need it (with an optional
|
|
|
# message):
|
|
|
ipshell('***Called from top level. '
|
|
|
'Hit Ctrl-D to exit interpreter and continue program.\n'
|
|
|
'Note that if you use %kill_embedded, you can fully deactivate\n'
|
|
|
'This embedded instance so it will never turn on again')
|
|
|
|
|
|
print '\nBack in caller program, moving along...\n'
|
|
|
|
|
|
#---------------------------------------------------------------------------
|
|
|
# More details:
|
|
|
|
|
|
# IPShellEmbed instances don't print the standard system banner and
|
|
|
# messages. The IPython banner (which actually may contain initialization
|
|
|
# messages) is available as <instance>.IP.BANNER in case you want it.
|
|
|
|
|
|
# IPShellEmbed instances print the following information everytime they
|
|
|
# start:
|
|
|
|
|
|
# - A global startup banner.
|
|
|
|
|
|
# - A call-specific header string, which you can use to indicate where in the
|
|
|
# execution flow the shell is starting.
|
|
|
|
|
|
# They also print an exit message every time they exit.
|
|
|
|
|
|
# Both the startup banner and the exit message default to None, and can be set
|
|
|
# either at the instance constructor or at any other time with the
|
|
|
# set_banner() and set_exit_msg() methods.
|
|
|
|
|
|
# The shell instance can be also put in 'dummy' mode globally or on a per-call
|
|
|
# basis. This gives you fine control for debugging without having to change
|
|
|
# code all over the place.
|
|
|
|
|
|
# The code below illustrates all this.
|
|
|
|
|
|
|
|
|
# This is how the global banner and exit_msg can be reset at any point
|
|
|
ipshell.set_banner('Entering interpreter - New Banner')
|
|
|
ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
|
|
|
|
|
|
def foo(m):
|
|
|
s = 'spam'
|
|
|
ipshell('***In foo(). Try @whos, or print s or m:')
|
|
|
print 'foo says m = ',m
|
|
|
|
|
|
def bar(n):
|
|
|
s = 'eggs'
|
|
|
ipshell('***In bar(). Try @whos, or print s or n:')
|
|
|
print 'bar says n = ',n
|
|
|
|
|
|
# Some calls to the above functions which will trigger IPython:
|
|
|
print 'Main program calling foo("eggs")\n'
|
|
|
foo('eggs')
|
|
|
|
|
|
# The shell can be put in 'dummy' mode where calls to it silently return. This
|
|
|
# allows you, for example, to globally turn off debugging for a program with a
|
|
|
# single call.
|
|
|
ipshell.set_dummy_mode(1)
|
|
|
print '\nTrying to call IPython which is now "dummy":'
|
|
|
ipshell()
|
|
|
print 'Nothing happened...'
|
|
|
# The global 'dummy' mode can still be overridden for a single call
|
|
|
print '\nOverriding dummy mode manually:'
|
|
|
ipshell(dummy=0)
|
|
|
|
|
|
# Reactivate the IPython shell
|
|
|
ipshell.set_dummy_mode(0)
|
|
|
|
|
|
print 'You can even have multiple embedded instances:'
|
|
|
ipshell2()
|
|
|
|
|
|
print '\nMain program calling bar("spam")\n'
|
|
|
bar('spam')
|
|
|
|
|
|
print 'Main program finished. Bye!'
|
|
|
|
|
|
#********************** End of file <example-embed.py> ***********************
|
|
|
|
|
|
Once you understand how the system functions, you can use the following
|
|
|
code fragments in your programs which are ready for cut and paste::
|
|
|
|
|
|
|
|
|
"""Quick code snippets for embedding IPython into other programs.
|
|
|
|
|
|
See example-embed.py for full details, this file has the bare minimum code for
|
|
|
cut and paste use once you understand how to use the system."""
|
|
|
|
|
|
#---------------------------------------------------------------------------
|
|
|
# This code loads IPython but modifies a few things if it detects it's running
|
|
|
# embedded in another IPython session (helps avoid confusion)
|
|
|
|
|
|
try:
|
|
|
__IPYTHON__
|
|
|
except NameError:
|
|
|
argv = ['']
|
|
|
banner = exit_msg = ''
|
|
|
else:
|
|
|
# Command-line options for IPython (a list like sys.argv)
|
|
|
argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:']
|
|
|
banner = '*** Nested interpreter ***'
|
|
|
exit_msg = '*** Back in main IPython ***'
|
|
|
|
|
|
# First import the embeddable shell class
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
# Now create the IPython shell instance. Put ipshell() anywhere in your code
|
|
|
# where you want it to open.
|
|
|
ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
|
|
|
|
|
|
#---------------------------------------------------------------------------
|
|
|
# This code will load an embeddable IPython shell always with no changes for
|
|
|
# nested embededings.
|
|
|
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
ipshell = IPShellEmbed()
|
|
|
# Now ipshell() will open IPython anywhere in the code.
|
|
|
|
|
|
#---------------------------------------------------------------------------
|
|
|
# This code loads an embeddable shell only if NOT running inside
|
|
|
# IPython. Inside IPython, the embeddable shell variable ipshell is just a
|
|
|
# dummy function.
|
|
|
|
|
|
try:
|
|
|
__IPYTHON__
|
|
|
except NameError:
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
ipshell = IPShellEmbed()
|
|
|
# Now ipshell() will open IPython anywhere in the code
|
|
|
else:
|
|
|
# Define a dummy ipshell() so the same code doesn't crash inside an
|
|
|
# interactive IPython
|
|
|
def ipshell(): pass
|
|
|
|
|
|
#******************* End of file <example-embed-short.py> ********************
|
|
|
|
|
|
Using the Python debugger (pdb)
|
|
|
===============================
|
|
|
|
|
|
Running entire programs via pdb
|
|
|
-------------------------------
|
|
|
|
|
|
pdb, the Python debugger, is a powerful interactive debugger which
|
|
|
allows you to step through code, set breakpoints, watch variables,
|
|
|
etc. IPython makes it very easy to start any script under the control
|
|
|
of pdb, regardless of whether you have wrapped it into a 'main()'
|
|
|
function or not. For this, simply type '%run -d myscript' at an
|
|
|
IPython prompt. See the %run command's documentation (via '%run?' or
|
|
|
in Sec. magic_ for more details, including how to control where pdb
|
|
|
will stop execution first.
|
|
|
|
|
|
For more information on the use of the pdb debugger, read the included
|
|
|
pdb.doc file (part of the standard Python distribution). On a stock
|
|
|
Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
|
|
|
easiest way to read it is by using the help() function of the pdb module
|
|
|
as follows (in an IPython prompt):
|
|
|
|
|
|
In [1]: import pdb
|
|
|
In [2]: pdb.help()
|
|
|
|
|
|
This will load the pdb.doc document in a file viewer for you automatically.
|
|
|
|
|
|
|
|
|
Automatic invocation of pdb on exceptions
|
|
|
-----------------------------------------
|
|
|
|
|
|
IPython, if started with the -pdb option (or if the option is set in
|
|
|
your rc file) can call the Python pdb debugger every time your code
|
|
|
triggers an uncaught exception. This feature
|
|
|
can also be toggled at any time with the %pdb magic command. This can be
|
|
|
extremely useful in order to find the origin of subtle bugs, because pdb
|
|
|
opens up at the point in your code which triggered the exception, and
|
|
|
while your program is at this point 'dead', all the data is still
|
|
|
available and you can walk up and down the stack frame and understand
|
|
|
the origin of the problem.
|
|
|
|
|
|
Furthermore, you can use these debugging facilities both with the
|
|
|
embedded IPython mode and without IPython at all. For an embedded shell
|
|
|
(see sec. Embedding_), simply call the constructor with
|
|
|
'-pdb' in the argument string and automatically pdb will be called if an
|
|
|
uncaught exception is triggered by your code.
|
|
|
|
|
|
For stand-alone use of the feature in your programs which do not use
|
|
|
IPython at all, put the following lines toward the top of your 'main'
|
|
|
routine::
|
|
|
|
|
|
import sys,IPython.ultraTB
|
|
|
sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
|
|
|
color_scheme='Linux', call_pdb=1)
|
|
|
|
|
|
The mode keyword can be either 'Verbose' or 'Plain', giving either very
|
|
|
detailed or normal tracebacks respectively. The color_scheme keyword can
|
|
|
be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
|
|
|
options which can be set in IPython with -colors and -xmode.
|
|
|
|
|
|
This will give any of your programs detailed, colored tracebacks with
|
|
|
automatic invocation of pdb.
|
|
|
|
|
|
|
|
|
Extensions for syntax processing
|
|
|
================================
|
|
|
|
|
|
This isn't for the faint of heart, because the potential for breaking
|
|
|
things is quite high. But it can be a very powerful and useful feature.
|
|
|
In a nutshell, you can redefine the way IPython processes the user input
|
|
|
line to accept new, special extensions to the syntax without needing to
|
|
|
change any of IPython's own code.
|
|
|
|
|
|
In the IPython/Extensions directory you will find some examples
|
|
|
supplied, which we will briefly describe now. These can be used 'as is'
|
|
|
(and both provide very useful functionality), or you can use them as a
|
|
|
starting point for writing your own extensions.
|
|
|
|
|
|
|
|
|
Pasting of code starting with '>>> ' or '... '
|
|
|
----------------------------------------------
|
|
|
|
|
|
In the python tutorial it is common to find code examples which have
|
|
|
been taken from real python sessions. The problem with those is that all
|
|
|
the lines begin with either '>>> ' or '... ', which makes it impossible
|
|
|
to paste them all at once. One must instead do a line by line manual
|
|
|
copying, carefully removing the leading extraneous characters.
|
|
|
|
|
|
This extension identifies those starting characters and removes them
|
|
|
from the input automatically, so that one can paste multi-line examples
|
|
|
directly into IPython, saving a lot of time. Please look at the file
|
|
|
InterpreterPasteInput.py in the IPython/Extensions directory for details
|
|
|
on how this is done.
|
|
|
|
|
|
IPython comes with a special profile enabling this feature, called
|
|
|
tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
|
|
|
will be available. In a normal IPython session you can activate the
|
|
|
feature by importing the corresponding module with:
|
|
|
In [1]: import IPython.Extensions.InterpreterPasteInput
|
|
|
|
|
|
The following is a 'screenshot' of how things work when this extension
|
|
|
is on, copying an example from the standard tutorial::
|
|
|
|
|
|
IPython profile: tutorial
|
|
|
|
|
|
*** Pasting of code with ">>>" or "..." has been enabled.
|
|
|
|
|
|
In [1]: >>> def fib2(n): # return Fibonacci series up to n
|
|
|
...: ... """Return a list containing the Fibonacci series up to
|
|
|
n."""
|
|
|
...: ... result = []
|
|
|
...: ... a, b = 0, 1
|
|
|
...: ... while b < n:
|
|
|
...: ... result.append(b) # see below
|
|
|
...: ... a, b = b, a+b
|
|
|
...: ... return result
|
|
|
...:
|
|
|
|
|
|
In [2]: fib2(10)
|
|
|
Out[2]: [1, 1, 2, 3, 5, 8]
|
|
|
|
|
|
Note that as currently written, this extension does not recognize
|
|
|
IPython's prompts for pasting. Those are more complicated, since the
|
|
|
user can change them very easily, they involve numbers and can vary in
|
|
|
length. One could however extract all the relevant information from the
|
|
|
IPython instance and build an appropriate regular expression. This is
|
|
|
left as an exercise for the reader.
|
|
|
|
|
|
|
|
|
Input of physical quantities with units
|
|
|
---------------------------------------
|
|
|
|
|
|
The module PhysicalQInput allows a simplified form of input for physical
|
|
|
quantities with units. This file is meant to be used in conjunction with
|
|
|
the PhysicalQInteractive module (in the same directory) and
|
|
|
Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
|
|
|
(http://dirac.cnrs-orleans.fr/ScientificPython/).
|
|
|
|
|
|
The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
|
|
|
but these must be declared as instances of a class. For example, to
|
|
|
define v as a velocity of 3 m/s, normally you would write::
|
|
|
|
|
|
In [1]: v = PhysicalQuantity(3,'m/s')
|
|
|
|
|
|
Using the PhysicalQ_Input extension this can be input instead as:
|
|
|
In [1]: v = 3 m/s
|
|
|
which is much more convenient for interactive use (even though it is
|
|
|
blatantly invalid Python syntax).
|
|
|
|
|
|
The physics profile supplied with IPython (enabled via 'ipython -p
|
|
|
physics') uses these extensions, which you can also activate with:
|
|
|
|
|
|
from math import * # math MUST be imported BEFORE PhysicalQInteractive
|
|
|
from IPython.Extensions.PhysicalQInteractive import *
|
|
|
import IPython.Extensions.PhysicalQInput
|
|
|
|
|
|
|
|
|
Threading support
|
|
|
=================
|
|
|
|
|
|
WARNING: The threading support is still somewhat experimental, and it
|
|
|
has only seen reasonable testing under Linux. Threaded code is
|
|
|
particularly tricky to debug, and it tends to show extremely
|
|
|
platform-dependent behavior. Since I only have access to Linux machines,
|
|
|
I will have to rely on user's experiences and assistance for this area
|
|
|
of IPython to improve under other platforms.
|
|
|
|
|
|
IPython, via the -gthread , -qthread, -q4thread and -wthread options
|
|
|
(described in Sec. `Threading options`_), can run in
|
|
|
multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications
|
|
|
respectively. These GUI toolkits need to control the python main loop of
|
|
|
execution, so under a normal Python interpreter, starting a pyGTK, Qt3,
|
|
|
Qt4 or WXPython application will immediately freeze the shell.
|
|
|
|
|
|
IPython, with one of these options (you can only use one at a time),
|
|
|
separates the graphical loop and IPython's code execution run into
|
|
|
different threads. This allows you to test interactively (with %run, for
|
|
|
example) your GUI code without blocking.
|
|
|
|
|
|
A nice mini-tutorial on using IPython along with the Qt Designer
|
|
|
application is available at the SciPy wiki:
|
|
|
http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
|
|
|
|
|
|
|
|
|
Tk issues
|
|
|
---------
|
|
|
|
|
|
As indicated in Sec. `Threading options`_, a special -tk option is
|
|
|
provided to try and allow Tk graphical applications to coexist
|
|
|
interactively with WX, Qt or GTK ones. Whether this works at all,
|
|
|
however, is very platform and configuration dependent. Please
|
|
|
experiment with simple test cases before committing to using this
|
|
|
combination of Tk and GTK/Qt/WX threading in a production environment.
|
|
|
|
|
|
|
|
|
I/O pitfalls
|
|
|
------------
|
|
|
|
|
|
Be mindful that the Python interpreter switches between threads every
|
|
|
$N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
|
|
|
value can be read by using the sys.getcheckinterval() function, and it
|
|
|
can be reset via sys.setcheckinterval(N). This switching of threads can
|
|
|
cause subtly confusing effects if one of your threads is doing file I/O.
|
|
|
In text mode, most systems only flush file buffers when they encounter a
|
|
|
'\n'. An instruction as simple as::
|
|
|
|
|
|
print >> filehandle, ''hello world''
|
|
|
|
|
|
actually consists of several bytecodes, so it is possible that the
|
|
|
newline does not reach your file before the next thread switch.
|
|
|
Similarly, if you are writing to a file in binary mode, the file won't
|
|
|
be flushed until the buffer fills, and your other thread may see
|
|
|
apparently truncated files.
|
|
|
|
|
|
For this reason, if you are using IPython's thread support and have (for
|
|
|
example) a GUI application which will read data generated by files
|
|
|
written to from the IPython thread, the safest approach is to open all
|
|
|
of your files in unbuffered mode (the third argument to the file/open
|
|
|
function is the buffering value)::
|
|
|
|
|
|
filehandle = open(filename,mode,0)
|
|
|
|
|
|
This is obviously a brute force way of avoiding race conditions with the
|
|
|
file buffering. If you want to do it cleanly, and you have a resource
|
|
|
which is being shared by the interactive IPython loop and your GUI
|
|
|
thread, you should really handle it with thread locking and
|
|
|
syncrhonization properties. The Python documentation discusses these.
|
|
|
|
|
|
.. _interactive_demos:
|
|
|
|
|
|
Interactive demos with IPython
|
|
|
==============================
|
|
|
|
|
|
IPython ships with a basic system for running scripts interactively in
|
|
|
sections, useful when presenting code to audiences. A few tags embedded
|
|
|
in comments (so that the script remains valid Python code) divide a file
|
|
|
into separate blocks, and the demo can be run one block at a time, with
|
|
|
IPython printing (with syntax highlighting) the block before executing
|
|
|
it, and returning to the interactive prompt after each block. The
|
|
|
interactive namespace is updated after each block is run with the
|
|
|
contents of the demo's namespace.
|
|
|
|
|
|
This allows you to show a piece of code, run it and then execute
|
|
|
interactively commands based on the variables just created. Once you
|
|
|
want to continue, you simply execute the next block of the demo. The
|
|
|
following listing shows the markup necessary for dividing a script into
|
|
|
sections for execution as a demo::
|
|
|
|
|
|
|
|
|
"""A simple interactive demo to illustrate the use of IPython's Demo class.
|
|
|
|
|
|
Any python script can be run as a demo, but that does little more than showing
|
|
|
it on-screen, syntax-highlighted in one shot. If you add a little simple
|
|
|
markup, you can stop at specified intervals and return to the ipython prompt,
|
|
|
resuming execution later.
|
|
|
"""
|
|
|
|
|
|
print 'Hello, welcome to an interactive IPython demo.'
|
|
|
print 'Executing this block should require confirmation before proceeding,'
|
|
|
print 'unless auto_all has been set to true in the demo object'
|
|
|
|
|
|
# The mark below defines a block boundary, which is a point where IPython will
|
|
|
# stop execution and return to the interactive prompt.
|
|
|
# Note that in actual interactive execution,
|
|
|
# <demo> --- stop ---
|
|
|
|
|
|
x = 1
|
|
|
y = 2
|
|
|
|
|
|
# <demo> --- stop ---
|
|
|
|
|
|
# the mark below makes this block as silent
|
|
|
# <demo> silent
|
|
|
|
|
|
print 'This is a silent block, which gets executed but not printed.'
|
|
|
|
|
|
# <demo> --- stop ---
|
|
|
# <demo> auto
|
|
|
print 'This is an automatic block.'
|
|
|
print 'It is executed without asking for confirmation, but printed.'
|
|
|
z = x+y
|
|
|
|
|
|
print 'z=',x
|
|
|
|
|
|
# <demo> --- stop ---
|
|
|
# This is just another normal block.
|
|
|
print 'z is now:', z
|
|
|
|
|
|
print 'bye!'
|
|
|
|
|
|
In order to run a file as a demo, you must first make a Demo object out
|
|
|
of it. If the file is named myscript.py, the following code will make a
|
|
|
demo::
|
|
|
|
|
|
from IPython.demo import Demo
|
|
|
|
|
|
mydemo = Demo('myscript.py')
|
|
|
|
|
|
This creates the mydemo object, whose blocks you run one at a time by
|
|
|
simply calling the object with no arguments. If you have autocall active
|
|
|
in IPython (the default), all you need to do is type::
|
|
|
|
|
|
mydemo
|
|
|
|
|
|
and IPython will call it, executing each block. Demo objects can be
|
|
|
restarted, you can move forward or back skipping blocks, re-execute the
|
|
|
last block, etc. Simply use the Tab key on a demo object to see its
|
|
|
methods, and call '?' on them to see their docstrings for more usage
|
|
|
details. In addition, the demo module itself contains a comprehensive
|
|
|
docstring, which you can access via::
|
|
|
|
|
|
from IPython import demo
|
|
|
|
|
|
demo?
|
|
|
|
|
|
Limitations: It is important to note that these demos are limited to
|
|
|
fairly simple uses. In particular, you can not put division marks in
|
|
|
indented code (loops, if statements, function definitions, etc.)
|
|
|
Supporting something like this would basically require tracking the
|
|
|
internal execution state of the Python interpreter, so only top-level
|
|
|
divisions are allowed. If you want to be able to open an IPython
|
|
|
instance at an arbitrary point in a program, you can use IPython's
|
|
|
embedding facilities, described in detail in Sec. 9
|
|
|
|
|
|
|
|
|
.. _Matplotlib support:
|
|
|
|
|
|
Plotting with matplotlib
|
|
|
========================
|
|
|
|
|
|
The matplotlib library (http://matplotlib.sourceforge.net
|
|
|
http://matplotlib.sourceforge.net) provides high quality 2D plotting for
|
|
|
Python. Matplotlib can produce plots on screen using a variety of GUI
|
|
|
toolkits, including Tk, GTK and WXPython. It also provides a number of
|
|
|
commands useful for scientific computing, all with a syntax compatible
|
|
|
with that of the popular Matlab program.
|
|
|
|
|
|
IPython accepts the special option -pylab (see :ref:`here
|
|
|
<command_line_options>`). This configures it to support matplotlib, honoring
|
|
|
the settings in the .matplotlibrc file. IPython will detect the user's choice
|
|
|
of matplotlib GUI backend, and automatically select the proper threading model
|
|
|
to prevent blocking. It also sets matplotlib in interactive mode and modifies
|
|
|
%run slightly, so that any matplotlib-based script can be executed using %run
|
|
|
and the final show() command does not block the interactive shell.
|
|
|
|
|
|
The -pylab option must be given first in order for IPython to configure its
|
|
|
threading mode. However, you can still issue other options afterwards. This
|
|
|
allows you to have a matplotlib-based environment customized with additional
|
|
|
modules using the standard IPython profile mechanism (see :ref:`here
|
|
|
<profiles>`): ``ipython -pylab -p myprofile`` will load the profile defined in
|
|
|
ipythonrc-myprofile after configuring matplotlib.
|
|
|
|
