3
3
======================
5
5
======================
7
IPython can be used as an improved replacement for the Python prompt,
8
and for that you don't really need to read any more of this manual. But
9
in this section we'll try to summarize a few tips on how to make the
10
most effective use of it for everyday Python development, highlighting
11
things you might miss in the rest of the manual (which is getting long).
12
We'll give references to parts in the manual which provide more detail
15
The following article by Jeremy Jones provides an introductory tutorial
16
about IPython: http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
7
You don't need to know anything beyond Python to start using IPython – just type
8
commands as you would at the standard Python prompt. But IPython can do much
9
more than the standard prompt. Some key features are described here. For more
10
information, check the :ref:`tips page <tips>`, or look at examples in the
11
`IPython cookbook <http://ipython.scipy.org/moin/Cookbook>`_.
13
If you've never used Python before, you might want to look at `the official
14
tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
15
Python <http://diveintopython.org/toc/index.html>`_.
24
TAB-completion, especially for attributes, is a convenient way to explore the
25
structure of any object you're dealing with. Simply type object_name.<TAB> and
26
a list of the object's attributes will be printed (see :ref:`the readline
27
section <readline>` for more). Tab completion also works on file and directory
28
names, which combined with IPython's alias system allows you to do from within
29
IPython many of the things you normally would need the system shell for.
34
Typing object_name? will print all sorts of details about any object,
20
Tab completion, especially for attributes, is a convenient way to explore the
21
structure of any object you're dealing with. Simply type ``object_name.<TAB>``
22
to view the object's attributes (see :ref:`the readline section <readline>` for
23
more). Besides Python objects and keywords, tab completion also works on file
26
Exploring your objects
27
======================
29
Typing ``object_name?`` will print all sorts of details about any object,
35
30
including docstrings, function definition lines (for call arguments) and
36
constructor details for classes. The magic commands %pdoc, %pdef, %psource
37
and %pfile will respectively print the docstring, function definition line,
38
full source code and the complete file for any object (when they can be
39
found). If automagic is on (it is by default), you don't need to type the '%'
40
explicitly. See :ref:`this section <dynamic_object_info>` for more.
42
The `%run` magic command
43
------------------------
31
constructor details for classes. To get specific information on an object, you
32
can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
37
IPython has a set of predefined 'magic functions' that you can call with a
38
command line style syntax. These include:
40
- Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
42
- Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``, etc.
43
- Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
45
You can always call these using the % prefix, and if you're typing one on a line
46
by itself, you can omit even that::
50
For more details on any magic function, call ``%somemagic?`` to read its
51
docstring. To see all the available magic functions, call ``%lsmagic``.
45
56
The %run magic command allows you to run any python script and load all of its
46
57
data directly into the interactive namespace. Since the file is re-read from
47
disk each time, changes you make to it are reflected immediately (in contrast
48
to the behavior of import). I rarely use import for code I am testing, relying
49
on %run instead. See :ref:`this section <magic>` for more on this and other
50
magic commands, or type the name of any magic command and ? to get details on
51
it. See also :ref:`this section <dreload>` for a recursive reload command. %run
52
also has special flags for timing the execution of your scripts (-t) and for
53
executing them under the control of either Python's pdb debugger (-d) or
54
profiler (-p). With all of these, %run can be used as the main tool for
55
efficient interactive development of code which you write in your editor of
61
Use the Python debugger, pdb. The %pdb command allows you to toggle on and off
62
the automatic invocation of an IPython-enhanced pdb debugger (with coloring,
63
tab completion and more) at any uncaught exception. The advantage of this is
64
that pdb starts inside the function where the exception occurred, with all data
65
still available. You can print variables, see code, execute statements and even
66
walk up and down the call stack to track down the true source of the problem
67
(which often is many layers in the stack above where the exception gets
68
triggered). Running programs with %run and pdb active can be an efficient to
69
develop and debug code, in many cases eliminating the need for print statements
70
or external debugging tools. I often simply put a 1/0 in a place where I want
71
to take a look so that pdb gets called, quickly view whatever variables I need
72
to or test various pieces of code and then remove the 1/0. Note also that '%run
73
-d' activates pdb and automatically sets initial breakpoints for you to step
74
through your code, watch variables, etc. The :ref:`output caching section
75
<output_caching>` has more details.
80
All output results are automatically stored in a global dictionary named Out
81
and variables named _1, _2, etc. alias them. For example, the result of input
82
line 4 is available either as Out[4] or as _4. Additionally, three variables
83
named _, __ and ___ are always kept updated with the for the last three
84
results. This allows you to recall any previous result and further use it for
85
new calculations. See :ref:`the output caching section <output_caching>` for
91
Put a ';' at the end of a line to suppress the printing of output. This is
92
useful when doing calculations which generate long output you are not
93
interested in seeing. The _* variables and the Out[] list do get updated with
94
the contents of the output, even if it is not printed. You can thus still
95
access the generated results this way for further processing.
100
A similar system exists for caching input. All input is stored in a global
101
list called In , so you can re-execute lines 22 through 28 plus line 34 by
102
typing 'exec In[22:29]+In[34]' (using Python slicing notation). If you need
103
to execute the same set of lines often, you can assign them to a macro with
104
the %macro function. See :ref:`here <input_caching>` for more.
106
Use your input history
107
----------------------
109
The %hist command can show you all previous input, without line numbers if
110
desired (option -n) so you can directly copy and paste code either back in
111
IPython or in a text editor. You can also save all your history by turning on
112
logging via %logstart; these logs can later be either reloaded as IPython
113
sessions or used as code for your programs.
58
disk each time, changes you make to it are reflected immediately (unlike
59
imported modules, which have to be specifically reloaded). IPython also includes
60
:ref:`dreload <dreload>`, a recursive reload function.
62
%run has special flags for timing the execution of your scripts (-t), or for
63
running them under the control of either Python's pdb debugger (-d) or
66
The %edit command gives a reasonable approximation of multiline editing,
67
by invoking your favorite editor on the spot. IPython will execute the
68
code you type in there as if it were typed interactively.
73
After an exception occurs, you can call ``%debug`` to jump into the Python
74
debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``,
75
IPython will automatically start the debugger on any uncaught exception. You can
76
print variables, see code, execute statements and even walk up and down the
77
call stack to track down the true source of the problem. Running programs with
78
%run and pdb active can be an efficient way to develop and debug code, in many
79
cases eliminating the need for print statements or external debugging tools.
81
You can also step through a program from the beginning by calling
82
``%run -d theprogram.py``.
87
IPython stores both the commands you enter, and the results it produces. You
88
can easily go through previous commands with the up- and down-arrow keys, or
89
access your history in more sophisticated ways.
91
Input and output history are kept in variables called ``In`` and ``Out``, which
92
can both be indexed by the prompt number on which they occurred, e.g. ``In[4]``.
93
The last three objects in output history are also kept in variables named ``_``,
96
You can use the ``%history`` magic function to examine past input and output.
97
Input history from previous sessions is saved in a database, and IPython can be
98
configured to save output history.
100
Several other magic functions can use your input history, including ``%edit``,
101
``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
102
standard format to refer to lines::
104
%pastebin 3 18-20 ~1/1-5
106
This will take line 3 and lines 18 to 20 from the current session, and lines
107
1-5 from the previous session.
109
System shell commands
110
=====================
112
To run any command at the system shell, simply prefix it with !, e.g.::
116
You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
117
the values of Python variables or expressions to system commands, prefix them
118
with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section
119
<system_shell_access>` for more details.
115
121
Define your own system aliases
116
122
------------------------------
118
Even though IPython gives you access to your system shell via the ! prefix,
119
it is convenient to have aliases to the system commands you use most often.
124
It's convenient to have aliases to the system commands you use most often.
120
125
This allows you to work seamlessly from inside IPython with the same commands
121
126
you are used to in your system shell. IPython comes with some pre-defined
122
127
aliases and a complete system for changing directories, both via a stack (see
123
128
%pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
124
129
visited directories and allows you to go to any previously visited one.
126
Call system shell commands
127
--------------------------
129
Use Python to manipulate the results of system commands. The '!!' special
130
syntax, and the %sc and %sx magic commands allow you to capture system output
131
into Python variables.
133
Use Python variables when calling the shell
134
-------------------------------------------
136
Expand python variables when calling the shell (either via '!' and '!!' or via
137
aliases) by prepending a $ in front of them. You can also expand complete
138
python expressions. See :ref:`our shell section <system_shell_access>` for
144
Use profiles to maintain different configurations (modules to load, function
145
definitions, option settings) for particular tasks. You can then have
146
customized versions of IPython for specific purposes. :ref:`This section
147
<profiles>` has more details.
150
Embed IPython in your programs
151
------------------------------
153
A few lines of code are enough to load a complete IPython inside your own
154
programs, giving you the ability to work with your data interactively after
155
automatic processing has been completed. See :ref:`here <embedding>` for more.
157
Use the Python profiler
158
-----------------------
160
When dealing with performance issues, the %run command with a -p option
161
allows you to run complete programs under the control of the Python profiler.
162
The %prun command does a similar job for single Python expressions (like
165
Use IPython to present interactive demos
166
----------------------------------------
168
Use the IPython.demo.Demo class to load any Python script as an interactive
169
demo. With a minimal amount of simple markup, you can control the execution of
170
the script, stopping as needed. See :ref:`here <interactive_demos>` for more.
175
Run your doctests from within IPython for development and debugging. The
176
special %doctest_mode command toggles a mode where the prompt, output and
177
exceptions display matches as closely as possible that of the default Python
178
interpreter. In addition, this mode allows you to directly paste in code that
179
contains leading '>>>' prompts, even if they have extra leading whitespace
180
(as is common in doctest files). This combined with the '%history -tn' call
181
to see your translated history (with these extra prompts removed and no line
182
numbers) allows for an easy doctest workflow, where you can go from doctest
183
to interactive execution to pasting into valid Python code as needed.
185
Source code handling tips
186
=========================
188
IPython is a line-oriented program, without full control of the
189
terminal. Therefore, it doesn't support true multiline editing. However,
190
it has a number of useful tools to help you in dealing effectively with
191
more complex editing.
193
The %edit command gives a reasonable approximation of multiline editing,
194
by invoking your favorite editor on the spot. IPython will execute the
195
code you type in there as if it were typed interactively. Type %edit?
196
for the full details on the edit command.
198
If you have typed various commands during a session, which you'd like to
199
reuse, IPython provides you with a number of tools. Start by using %hist
200
to see your input history, so you can see the line numbers of all input.
201
Let us say that you'd like to reuse lines 10 through 20, plus lines 24
202
and 28. All the commands below can operate on these with the syntax::
206
where the command given can be:
208
* %macro <macroname>: this stores the lines into a variable which,
209
when called at the prompt, re-executes the input. Macros can be
210
edited later using '%edit macroname', and they can be stored
211
persistently across sessions with '%store macroname' (the storage
212
system is per-profile). The combination of quick macros,
213
persistent storage and editing, allows you to easily refine
214
quick-and-dirty interactive input into permanent utilities, always
215
available both in IPython and as files for general reuse.
216
* %edit: this will open a text editor with those lines pre-loaded
217
for further modification. It will then execute the resulting
218
file's contents as if you had typed it at the prompt.
219
* %save <filename>: this saves the lines directly to a named file on
222
While %macro saves input lines into memory for interactive re-execution,
223
sometimes you'd like to save your input directly to a file. The %save
224
magic does this: its input sytnax is the same as %macro, but it saves
225
your input directly to a Python file. Note that the %logstart command
226
also saves input, but it logs all input to disk (though you can
227
temporarily suspend it and reactivate it with %logoff/%logon); %save
228
allows you to select which lines of input you need to save.
231
Lightweight 'version control'
232
=============================
234
When you call %edit with no arguments, IPython opens an empty editor
235
with a temporary file, and it returns the contents of your editing
236
session as a string variable. Thanks to IPython's output caching
237
mechanism, this is automatically stored::
241
IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
243
Editing... done. Executing edited code...
245
hello - this is a temporary file
247
Out[1]: "print 'hello - this is a temporary file'\n"
249
Now, if you call '%edit -p', IPython tries to open an editor with the
250
same data as the last time you used %edit. So if you haven't used %edit
251
in the meantime, this same contents will reopen; however, it will be
252
done in a new file. This means that if you make changes and you later
253
want to find an old version, you can always retrieve it by using its
254
output number, via '%edit _NN', where NN is the number of the output
257
Continuing with the example above, this should illustrate this idea::
261
IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
263
Editing... done. Executing edited code...
265
hello - now I made some changes
267
Out[2]: "print 'hello - now I made some changes'\n"
271
IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
273
Editing... done. Executing edited code...
275
hello - this is a temporary file
277
IPython version control at work :)
279
Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
282
This section was written after a contribution by Alexander Belchenko on
283
the IPython user list.
289
A very useful suggestion sent in by Robert Kern follows:
291
I recently happened on a nifty way to keep tidy per-project log files. I
292
made a profile for my project (which is called "parkfield")::
296
# cancel earlier logfile invocation:
302
execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
304
execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
306
I also added a shell alias for convenience::
308
alias parkfield="ipython -pylab -profile parkfield"
310
Now I have a nice little directory with everything I ever type in,
311
organized by project and date.
317
Here is an alternative logging solution that lets you record your sessions in
318
a daily time-stamped log-files.
320
Add the following lines or make it a-like to your ipy_user_conf.py::
322
from time import strftime
327
ldir = '/home/$YOUR_USERNAME_HERE/.ipython/'
328
filename = os.path.join(ldir, strftime('%Y-%m-%d')+".py")
329
notnew = os.path.exists(filename)
330
ip.IP.logger.logstart(logfname=filename, logmode='append')
331
log_write = ip.IP.logger.log_write
333
log_write("# =================================")
335
log_write("#!/usr/bin/env python \n# %s.py \n"
336
"# IPython automatic logging file" %
337
strftime('%Y-%m-%d'))
338
log_write("# %s \n# =================================" %
340
print " Logging to "+filename
343
print " Already logging to "+ip.IP.logger.logfname
346
Contribute your own: If you have your own favorite tip on using IPython
347
efficiently for a certain task (especially things which can't be done in
348
the normal Python interpreter), don't hesitate to send it!
135
Much of IPython can be tweaked through configuration. To get started, use the
136
command ``ipython profile create`` to produce the default config files. These
137
will be placed in :file:`~/.ipython/profile_default` or
138
:file:`~/.config/ipython/profile_default`, and contain comments explaining what
139
the various options do.
141
Profiles allow you to use IPython for different tasks, keeping separate config
142
files and history for each one. More details in :ref:`the profiles section
added
removed
docs/source/interactive/tutorial.txt
