|
@@
-1,1150
+1,1150
b''
|
|
1
|
=================
|
|
1
|
=================
|
|
2
|
IPython reference
|
|
2
|
IPython reference
|
|
3
|
=================
|
|
3
|
=================
|
|
4
|
|
|
4
|
|
|
5
|
.. _command_line_options:
|
|
5
|
.. _command_line_options:
|
|
6
|
|
|
6
|
|
|
7
|
Command-line usage
|
|
7
|
Command-line usage
|
|
8
|
==================
|
|
8
|
==================
|
|
9
|
|
|
9
|
|
|
10
|
You start IPython with the command::
|
|
10
|
You start IPython with the command::
|
|
11
|
|
|
11
|
|
|
12
|
$ ipython [options] files
|
|
12
|
$ ipython [options] files
|
|
13
|
|
|
13
|
|
|
14
|
.. note::
|
|
14
|
.. note::
|
|
15
|
|
|
15
|
|
|
16
|
For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
|
|
16
|
For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
|
|
17
|
|
|
17
|
|
|
18
|
If invoked with no options, it executes all the files listed in sequence
|
|
18
|
If invoked with no options, it executes all the files listed in sequence
|
|
19
|
and drops you into the interpreter while still acknowledging any options
|
|
19
|
and drops you into the interpreter while still acknowledging any options
|
|
20
|
you may have set in your ipython_config.py. This behavior is different from
|
|
20
|
you may have set in your ipython_config.py. This behavior is different from
|
|
21
|
standard Python, which when called as python -i will only execute one
|
|
21
|
standard Python, which when called as python -i will only execute one
|
|
22
|
file and ignore your configuration setup.
|
|
22
|
file and ignore your configuration setup.
|
|
23
|
|
|
23
|
|
|
24
|
Please note that some of the configuration options are not available at
|
|
24
|
Please note that some of the configuration options are not available at
|
|
25
|
the command line, simply because they are not practical here. Look into
|
|
25
|
the command line, simply because they are not practical here. Look into
|
|
26
|
your configuration files for details on those. There are separate configuration
|
|
26
|
your configuration files for details on those. There are separate configuration
|
|
27
|
files for each profile, and the files look like "ipython_config.py" or
|
|
27
|
files for each profile, and the files look like "ipython_config.py" or
|
|
28
|
"ipython_config_<frontendname>.py". Profile directories look like
|
|
28
|
"ipython_config_<frontendname>.py". Profile directories look like
|
|
29
|
"profile_profilename" and are typically installed in the IPYTHONDIR directory.
|
|
29
|
"profile_profilename" and are typically installed in the IPYTHONDIR directory.
|
|
30
|
For Linux users, this will be $HOME/.config/ipython, and for other users it
|
|
30
|
For Linux users, this will be $HOME/.config/ipython, and for other users it
|
|
31
|
will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and
|
|
31
|
will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and
|
|
32
|
Settings\\YourUserName in most instances.
|
|
32
|
Settings\\YourUserName in most instances.
|
|
33
|
|
|
33
|
|
|
34
|
|
|
34
|
|
|
35
|
Eventloop integration
|
|
35
|
Eventloop integration
|
|
36
|
---------------------
|
|
36
|
---------------------
|
|
37
|
|
|
37
|
|
|
38
|
Previously IPython had command line options for controlling GUI event loop
|
|
38
|
Previously IPython had command line options for controlling GUI event loop
|
|
39
|
integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
|
|
39
|
integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
|
|
40
|
version 0.11, these have been removed. Please see the new ``%gui``
|
|
40
|
version 0.11, these have been removed. Please see the new ``%gui``
|
|
41
|
magic command or :ref:`this section <gui_support>` for details on the new
|
|
41
|
magic command or :ref:`this section <gui_support>` for details on the new
|
|
42
|
interface, or specify the gui at the commandline::
|
|
42
|
interface, or specify the gui at the commandline::
|
|
43
|
|
|
43
|
|
|
44
|
$ ipython --gui=qt
|
|
44
|
$ ipython --gui=qt
|
|
45
|
|
|
45
|
|
|
46
|
|
|
46
|
|
|
47
|
Command-line Options
|
|
47
|
Command-line Options
|
|
48
|
--------------------
|
|
48
|
--------------------
|
|
49
|
|
|
49
|
|
|
50
|
To see the options IPython accepts, use ``ipython --help`` (and you probably
|
|
50
|
To see the options IPython accepts, use ``ipython --help`` (and you probably
|
|
51
|
should run the output through a pager such as ``ipython --help | less`` for
|
|
51
|
should run the output through a pager such as ``ipython --help | less`` for
|
|
52
|
more convenient reading). This shows all the options that have a single-word
|
|
52
|
more convenient reading). This shows all the options that have a single-word
|
|
53
|
alias to control them, but IPython lets you configure all of its objects from
|
|
53
|
alias to control them, but IPython lets you configure all of its objects from
|
|
54
|
the command-line by passing the full class name and a corresponding value; type
|
|
54
|
the command-line by passing the full class name and a corresponding value; type
|
|
55
|
``ipython --help-all`` to see this full list. For example::
|
|
55
|
``ipython --help-all`` to see this full list. For example::
|
|
56
|
|
|
56
|
|
|
57
|
ipython --pylab qt
|
|
57
|
ipython --pylab qt
|
|
58
|
|
|
58
|
|
|
59
|
is equivalent to::
|
|
59
|
is equivalent to::
|
|
60
|
|
|
60
|
|
|
61
|
ipython --TerminalIPythonApp.pylab='qt'
|
|
61
|
ipython --TerminalIPythonApp.pylab='qt'
|
|
62
|
|
|
62
|
|
|
63
|
Note that in the second form, you *must* use the equal sign, as the expression
|
|
63
|
Note that in the second form, you *must* use the equal sign, as the expression
|
|
64
|
is evaluated as an actual Python assignment. While in the above example the
|
|
64
|
is evaluated as an actual Python assignment. While in the above example the
|
|
65
|
short form is more convenient, only the most common options have a short form,
|
|
65
|
short form is more convenient, only the most common options have a short form,
|
|
66
|
while any configurable variable in IPython can be set at the command-line by
|
|
66
|
while any configurable variable in IPython can be set at the command-line by
|
|
67
|
using the long form. This long form is the same syntax used in the
|
|
67
|
using the long form. This long form is the same syntax used in the
|
|
68
|
configuration files, if you want to set these options permanently.
|
|
68
|
configuration files, if you want to set these options permanently.
|
|
69
|
|
|
69
|
|
|
70
|
|
|
70
|
|
|
71
|
Interactive use
|
|
71
|
Interactive use
|
|
72
|
===============
|
|
72
|
===============
|
|
73
|
|
|
73
|
|
|
74
|
IPython is meant to work as a drop-in replacement for the standard interactive
|
|
74
|
IPython is meant to work as a drop-in replacement for the standard interactive
|
|
75
|
interpreter. As such, any code which is valid python should execute normally
|
|
75
|
interpreter. As such, any code which is valid python should execute normally
|
|
76
|
under IPython (cases where this is not true should be reported as bugs). It
|
|
76
|
under IPython (cases where this is not true should be reported as bugs). It
|
|
77
|
does, however, offer many features which are not available at a standard python
|
|
77
|
does, however, offer many features which are not available at a standard python
|
|
78
|
prompt. What follows is a list of these.
|
|
78
|
prompt. What follows is a list of these.
|
|
79
|
|
|
79
|
|
|
80
|
|
|
80
|
|
|
81
|
Caution for Windows users
|
|
81
|
Caution for Windows users
|
|
82
|
-------------------------
|
|
82
|
-------------------------
|
|
83
|
|
|
83
|
|
|
84
|
Windows, unfortunately, uses the '\\' character as a path separator. This is a
|
|
84
|
Windows, unfortunately, uses the '\\' character as a path separator. This is a
|
|
85
|
terrible choice, because '\\' also represents the escape character in most
|
|
85
|
terrible choice, because '\\' also represents the escape character in most
|
|
86
|
modern programming languages, including Python. For this reason, using '/'
|
|
86
|
modern programming languages, including Python. For this reason, using '/'
|
|
87
|
character is recommended if you have problems with ``\``. However, in Windows
|
|
87
|
character is recommended if you have problems with ``\``. However, in Windows
|
|
88
|
commands '/' flags options, so you can not use it for the root directory. This
|
|
88
|
commands '/' flags options, so you can not use it for the root directory. This
|
|
89
|
means that paths beginning at the root must be typed in a contrived manner
|
|
89
|
means that paths beginning at the root must be typed in a contrived manner
|
|
90
|
like: ``%copy \opt/foo/bar.txt \tmp``
|
|
90
|
like: ``%copy \opt/foo/bar.txt \tmp``
|
|
91
|
|
|
91
|
|
|
92
|
.. _magic:
|
|
92
|
.. _magic:
|
|
93
|
|
|
93
|
|
|
94
|
Magic command system
|
|
94
|
Magic command system
|
|
95
|
--------------------
|
|
95
|
--------------------
|
|
96
|
|
|
96
|
|
|
97
|
IPython will treat any line whose first character is a % as a special
|
|
97
|
IPython will treat any line whose first character is a % as a special
|
|
98
|
call to a 'magic' function. These allow you to control the behavior of
|
|
98
|
call to a 'magic' function. These allow you to control the behavior of
|
|
99
|
IPython itself, plus a lot of system-type features. They are all
|
|
99
|
IPython itself, plus a lot of system-type features. They are all
|
|
100
|
prefixed with a % character, but parameters are given without
|
|
100
|
prefixed with a % character, but parameters are given without
|
|
101
|
parentheses or quotes.
|
|
101
|
parentheses or quotes.
|
|
102
|
|
|
102
|
|
|
103
|
Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
|
|
103
|
Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
|
|
104
|
only the rest of the current line, but all lines below them as well, in the
|
|
104
|
only the rest of the current line, but all lines below them as well, in the
|
|
105
|
current execution block. Cell magics can in fact make arbitrary modifications
|
|
105
|
current execution block. Cell magics can in fact make arbitrary modifications
|
|
106
|
to the input they receive, which need not even be valid Python code at all.
|
|
106
|
to the input they receive, which need not even be valid Python code at all.
|
|
107
|
They receive the whole block as a single string.
|
|
107
|
They receive the whole block as a single string.
|
|
108
|
|
|
108
|
|
|
109
|
As a line magic example, the ``%cd`` magic works just like the OS command of
|
|
109
|
As a line magic example, the ``%cd`` magic works just like the OS command of
|
|
110
|
the same name::
|
|
110
|
the same name::
|
|
111
|
|
|
111
|
|
|
112
|
In [8]: %cd
|
|
112
|
In [8]: %cd
|
|
113
|
/home/fperez
|
|
113
|
/home/fperez
|
|
114
|
|
|
114
|
|
|
115
|
The following uses the builtin ``timeit`` in cell mode::
|
|
115
|
The following uses the builtin ``timeit`` in cell mode::
|
|
116
|
|
|
116
|
|
|
117
|
In [10]: %%timeit x = range(10000)
|
|
117
|
In [10]: %%timeit x = range(10000)
|
|
118
|
...: min(x)
|
|
118
|
...: min(x)
|
|
119
|
...: max(x)
|
|
119
|
...: max(x)
|
|
120
|
...:
|
|
120
|
...:
|
|
121
|
1000 loops, best of 3: 438 us per loop
|
|
121
|
1000 loops, best of 3: 438 us per loop
|
|
122
|
|
|
122
|
|
|
123
|
In this case, ``x = range(10000)`` is called as the line argument, and the
|
|
123
|
In this case, ``x = range(10000)`` is called as the line argument, and the
|
|
124
|
block with ``min(x)`` and ``max(x)`` is called as the cell body. The
|
|
124
|
block with ``min(x)`` and ``max(x)`` is called as the cell body. The
|
|
125
|
``timeit`` magic receives both.
|
|
125
|
``timeit`` magic receives both.
|
|
126
|
|
|
126
|
|
|
127
|
If you have 'automagic' enabled (as it by default), you don't need to type in
|
|
127
|
If you have 'automagic' enabled (as it by default), you don't need to type in
|
|
128
|
the single ``%`` explicitly for line magics; IPython will scan its internal
|
|
128
|
the single ``%`` explicitly for line magics; IPython will scan its internal
|
|
129
|
list of magic functions and call one if it exists. With automagic on you can
|
|
129
|
list of magic functions and call one if it exists. With automagic on you can
|
|
130
|
then just type ``cd mydir`` to go to directory 'mydir'::
|
|
130
|
then just type ``cd mydir`` to go to directory 'mydir'::
|
|
131
|
|
|
131
|
|
|
132
|
In [9]: cd mydir
|
|
132
|
In [9]: cd mydir
|
|
133
|
/home/fperez/mydir
|
|
133
|
/home/fperez/mydir
|
|
134
|
|
|
134
|
|
|
135
|
Note that cell magics *always* require an explicit ``%%`` prefix, automagic
|
|
135
|
Note that cell magics *always* require an explicit ``%%`` prefix, automagic
|
|
136
|
calling only works for line magics.
|
|
136
|
calling only works for line magics.
|
|
137
|
|
|
137
|
|
|
138
|
The automagic system has the lowest possible precedence in name searches, so
|
|
138
|
The automagic system has the lowest possible precedence in name searches, so
|
|
139
|
defining an identifier with the same name as an existing magic function will
|
|
139
|
defining an identifier with the same name as an existing magic function will
|
|
140
|
shadow it for automagic use. You can still access the shadowed magic function
|
|
140
|
shadow it for automagic use. You can still access the shadowed magic function
|
|
141
|
by explicitly using the ``%`` character at the beginning of the line.
|
|
141
|
by explicitly using the ``%`` character at the beginning of the line.
|
|
142
|
|
|
142
|
|
|
143
|
An example (with automagic on) should clarify all this:
|
|
143
|
An example (with automagic on) should clarify all this:
|
|
144
|
|
|
144
|
|
|
145
|
.. sourcecode:: ipython
|
|
145
|
.. sourcecode:: ipython
|
|
146
|
|
|
146
|
|
|
147
|
In [1]: cd ipython # %cd is called by automagic
|
|
147
|
In [1]: cd ipython # %cd is called by automagic
|
|
148
|
/home/fperez/ipython
|
|
148
|
/home/fperez/ipython
|
|
149
|
|
|
149
|
|
|
150
|
In [2]: cd=1 # now cd is just a variable
|
|
150
|
In [2]: cd=1 # now cd is just a variable
|
|
151
|
|
|
151
|
|
|
152
|
In [3]: cd .. # and doesn't work as a function anymore
|
|
152
|
In [3]: cd .. # and doesn't work as a function anymore
|
|
153
|
File "<ipython-input-3-9fedb3aff56c>", line 1
|
|
153
|
File "<ipython-input-3-9fedb3aff56c>", line 1
|
|
154
|
cd ..
|
|
154
|
cd ..
|
|
155
|
^
|
|
155
|
^
|
|
156
|
SyntaxError: invalid syntax
|
|
156
|
SyntaxError: invalid syntax
|
|
157
|
|
|
157
|
|
|
158
|
|
|
158
|
|
|
159
|
In [4]: %cd .. # but %cd always works
|
|
159
|
In [4]: %cd .. # but %cd always works
|
|
160
|
/home/fperez
|
|
160
|
/home/fperez
|
|
161
|
|
|
161
|
|
|
162
|
In [5]: del cd # if you remove the cd variable, automagic works again
|
|
162
|
In [5]: del cd # if you remove the cd variable, automagic works again
|
|
163
|
|
|
163
|
|
|
164
|
In [6]: cd ipython
|
|
164
|
In [6]: cd ipython
|
|
165
|
|
|
165
|
|
|
166
|
/home/fperez/ipython
|
|
166
|
/home/fperez/ipython
|
|
167
|
|
|
167
|
|
|
168
|
Defining your own magics
|
|
168
|
Defining your own magics
|
|
169
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
169
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
170
|
|
|
170
|
|
|
171
|
There are two main ways to define your own magic functions: from standalone
|
|
171
|
There are two main ways to define your own magic functions: from standalone
|
|
172
|
functions and by inheriting from a base class provided by IPython:
|
|
172
|
functions and by inheriting from a base class provided by IPython:
|
|
173
|
:class:`IPython.core.magic.Magics`. Below we show code you can place in a file
|
|
173
|
:class:`IPython.core.magic.Magics`. Below we show code you can place in a file
|
|
174
|
that you load from your configuration, such as any file in the ``startup``
|
|
174
|
that you load from your configuration, such as any file in the ``startup``
|
|
175
|
subdirectory of your default IPython profile.
|
|
175
|
subdirectory of your default IPython profile.
|
|
176
|
|
|
176
|
|
|
177
|
First, let us see the simplest case. The following shows how to create a line
|
|
177
|
First, let us see the simplest case. The following shows how to create a line
|
|
178
|
magic, a cell one and one that works in both modes, using just plain functions:
|
|
178
|
magic, a cell one and one that works in both modes, using just plain functions:
|
|
179
|
|
|
179
|
|
|
180
|
.. sourcecode:: python
|
|
180
|
.. sourcecode:: python
|
|
181
|
|
|
181
|
|
|
182
|
from IPython.core.magic import (register_line_magic, register_cell_magic,
|
|
182
|
from IPython.core.magic import (register_line_magic, register_cell_magic,
|
|
183
|
register_line_cell_magic)
|
|
183
|
register_line_cell_magic)
|
|
184
|
|
|
184
|
|
|
185
|
@register_line_magic
|
|
185
|
@register_line_magic
|
|
186
|
def lmagic(line):
|
|
186
|
def lmagic(line):
|
|
187
|
"my line magic"
|
|
187
|
"my line magic"
|
|
188
|
return line
|
|
188
|
return line
|
|
189
|
|
|
189
|
|
|
190
|
@register_cell_magic
|
|
190
|
@register_cell_magic
|
|
191
|
def cmagic(line, cell):
|
|
191
|
def cmagic(line, cell):
|
|
192
|
"my cell magic"
|
|
192
|
"my cell magic"
|
|
193
|
return line, cell
|
|
193
|
return line, cell
|
|
194
|
|
|
194
|
|
|
195
|
@register_line_cell_magic
|
|
195
|
@register_line_cell_magic
|
|
196
|
def lcmagic(line, cell=None):
|
|
196
|
def lcmagic(line, cell=None):
|
|
197
|
"Magic that works both as %lcmagic and as %%lcmagic"
|
|
197
|
"Magic that works both as %lcmagic and as %%lcmagic"
|
|
198
|
if cell is None:
|
|
198
|
if cell is None:
|
|
199
|
print "Called as line magic"
|
|
199
|
print "Called as line magic"
|
|
200
|
return line
|
|
200
|
return line
|
|
201
|
else:
|
|
201
|
else:
|
|
202
|
print "Called as cell magic"
|
|
202
|
print "Called as cell magic"
|
|
203
|
return line, cell
|
|
203
|
return line, cell
|
|
204
|
|
|
204
|
|
|
205
|
# We delete these to avoid name conflicts for automagic to work
|
|
205
|
# We delete these to avoid name conflicts for automagic to work
|
|
206
|
del lmagic, lcmagic
|
|
206
|
del lmagic, lcmagic
|
|
207
|
|
|
207
|
|
|
208
|
|
|
208
|
|
|
209
|
You can also create magics of all three kinds by inheriting from the
|
|
209
|
You can also create magics of all three kinds by inheriting from the
|
|
210
|
:class:`IPython.core.magic.Magics` class. This lets you create magics that can
|
|
210
|
:class:`IPython.core.magic.Magics` class. This lets you create magics that can
|
|
211
|
potentially hold state in between calls, and that have full access to the main
|
|
211
|
potentially hold state in between calls, and that have full access to the main
|
|
212
|
IPython object:
|
|
212
|
IPython object:
|
|
213
|
|
|
213
|
|
|
214
|
.. sourcecode:: python
|
|
214
|
.. sourcecode:: python
|
|
215
|
|
|
215
|
|
|
216
|
# This code can be put in any Python module, it does not require IPython
|
|
216
|
# This code can be put in any Python module, it does not require IPython
|
|
217
|
# itself to be running already. It only creates the magics subclass but
|
|
217
|
# itself to be running already. It only creates the magics subclass but
|
|
218
|
# doesn't instantiate it yet.
|
|
218
|
# doesn't instantiate it yet.
|
|
219
|
from IPython.core.magic import (Magics, magics_class, line_magic,
|
|
219
|
from IPython.core.magic import (Magics, magics_class, line_magic,
|
|
220
|
cell_magic, line_cell_magic)
|
|
220
|
cell_magic, line_cell_magic)
|
|
221
|
|
|
221
|
|
|
222
|
# The class MUST call this class decorator at creation time
|
|
222
|
# The class MUST call this class decorator at creation time
|
|
223
|
@magics_class
|
|
223
|
@magics_class
|
|
224
|
class MyMagics(Magics):
|
|
224
|
class MyMagics(Magics):
|
|
225
|
|
|
225
|
|
|
226
|
@line_magic
|
|
226
|
@line_magic
|
|
227
|
def lmagic(self, line):
|
|
227
|
def lmagic(self, line):
|
|
228
|
"my line magic"
|
|
228
|
"my line magic"
|
|
229
|
print "Full access to the main IPython object:", self.shell
|
|
229
|
print "Full access to the main IPython object:", self.shell
|
|
230
|
print "Variables in the user namespace:", self.shell.user_ns.keys()
|
|
230
|
print "Variables in the user namespace:", self.shell.user_ns.keys()
|
|
231
|
return line
|
|
231
|
return line
|
|
232
|
|
|
232
|
|
|
233
|
@cell_magic
|
|
233
|
@cell_magic
|
|
234
|
def cmagic(self, line, cell):
|
|
234
|
def cmagic(self, line, cell):
|
|
235
|
"my cell magic"
|
|
235
|
"my cell magic"
|
|
236
|
return line, cell
|
|
236
|
return line, cell
|
|
237
|
|
|
237
|
|
|
238
|
@line_cell_magic
|
|
238
|
@line_cell_magic
|
|
239
|
def lcmagic(self, line, cell=None):
|
|
239
|
def lcmagic(self, line, cell=None):
|
|
240
|
"Magic that works both as %lcmagic and as %%lcmagic"
|
|
240
|
"Magic that works both as %lcmagic and as %%lcmagic"
|
|
241
|
if cell is None:
|
|
241
|
if cell is None:
|
|
242
|
print "Called as line magic"
|
|
242
|
print "Called as line magic"
|
|
243
|
return line
|
|
243
|
return line
|
|
244
|
else:
|
|
244
|
else:
|
|
245
|
print "Called as cell magic"
|
|
245
|
print "Called as cell magic"
|
|
246
|
return line, cell
|
|
246
|
return line, cell
|
|
247
|
|
|
247
|
|
|
248
|
|
|
248
|
|
|
249
|
# In order to actually use these magics, you must register them with a
|
|
249
|
# In order to actually use these magics, you must register them with a
|
|
250
|
# running IPython. This code must be placed in a file that is loaded once
|
|
250
|
# running IPython. This code must be placed in a file that is loaded once
|
|
251
|
# IPython is up and running:
|
|
251
|
# IPython is up and running:
|
|
252
|
ip = get_ipython()
|
|
252
|
ip = get_ipython()
|
|
253
|
# You can register the class itself without instantiating it. IPython will
|
|
253
|
# You can register the class itself without instantiating it. IPython will
|
|
254
|
# call the default constructor on it.
|
|
254
|
# call the default constructor on it.
|
|
255
|
ip.register_magics(MyMagics)
|
|
255
|
ip.register_magics(MyMagics)
|
|
256
|
|
|
256
|
|
|
257
|
If you want to create a class with a different constructor that holds
|
|
257
|
If you want to create a class with a different constructor that holds
|
|
258
|
additional state, then you should always call the parent constructor and
|
|
258
|
additional state, then you should always call the parent constructor and
|
|
259
|
instantiate the class yourself before registration:
|
|
259
|
instantiate the class yourself before registration:
|
|
260
|
|
|
260
|
|
|
261
|
.. sourcecode:: python
|
|
261
|
.. sourcecode:: python
|
|
262
|
|
|
262
|
|
|
263
|
@magics_class
|
|
263
|
@magics_class
|
|
264
|
class StatefulMagics(Magics):
|
|
264
|
class StatefulMagics(Magics):
|
|
265
|
"Magics that hold additional state"
|
|
265
|
"Magics that hold additional state"
|
|
266
|
|
|
266
|
|
|
267
|
def __init__(self, shell, data):
|
|
267
|
def __init__(self, shell, data):
|
|
268
|
# You must call the parent constructor
|
|
268
|
# You must call the parent constructor
|
|
269
|
super(StatefulMagics, self).__init__(shell)
|
|
269
|
super(StatefulMagics, self).__init__(shell)
|
|
270
|
self.data = data
|
|
270
|
self.data = data
|
|
271
|
|
|
271
|
|
|
272
|
# etc...
|
|
272
|
# etc...
|
|
273
|
|
|
273
|
|
|
274
|
# This class must then be registered with a manually created instance,
|
|
274
|
# This class must then be registered with a manually created instance,
|
|
275
|
# since its constructor has different arguments from the default:
|
|
275
|
# since its constructor has different arguments from the default:
|
|
276
|
ip = get_ipython()
|
|
276
|
ip = get_ipython()
|
|
277
|
magics = StatefulMagics(ip, some_data)
|
|
277
|
magics = StatefulMagics(ip, some_data)
|
|
278
|
ip.register_magics(magics)
|
|
278
|
ip.register_magics(magics)
|
|
279
|
|
|
279
|
|
|
280
|
|
|
280
|
|
|
281
|
In earlier versions, IPython had an API for the creation of line magics (cell
|
|
281
|
In earlier versions, IPython had an API for the creation of line magics (cell
|
|
282
|
magics did not exist at the time) that required you to create functions with a
|
|
282
|
magics did not exist at the time) that required you to create functions with a
|
|
283
|
method-looking signature and to manually pass both the function and the name.
|
|
283
|
method-looking signature and to manually pass both the function and the name.
|
|
284
|
While this API is no longer recommended, it remains indefinitely supported for
|
|
284
|
While this API is no longer recommended, it remains indefinitely supported for
|
|
285
|
backwards compatibility purposes. With the old API, you'd create a magic as
|
|
285
|
backwards compatibility purposes. With the old API, you'd create a magic as
|
|
286
|
follows:
|
|
286
|
follows:
|
|
287
|
|
|
287
|
|
|
288
|
.. sourcecode:: python
|
|
288
|
.. sourcecode:: python
|
|
289
|
|
|
289
|
|
|
290
|
def func(self, line):
|
|
290
|
def func(self, line):
|
|
291
|
print "Line magic called with line:", line
|
|
291
|
print "Line magic called with line:", line
|
|
292
|
print "IPython object:", self.shell
|
|
292
|
print "IPython object:", self.shell
|
|
293
|
|
|
293
|
|
|
294
|
ip = get_ipython()
|
|
294
|
ip = get_ipython()
|
|
295
|
# Declare this function as the magic %mycommand
|
|
295
|
# Declare this function as the magic %mycommand
|
|
296
|
ip.define_magic('mycommand', func)
|
|
296
|
ip.define_magic('mycommand', func)
|
|
297
|
|
|
297
|
|
|
298
|
Type ``%magic`` for more information, including a list of all available magic
|
|
298
|
Type ``%magic`` for more information, including a list of all available magic
|
|
299
|
functions at any time and their docstrings. You can also type
|
|
299
|
functions at any time and their docstrings. You can also type
|
|
300
|
``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
|
|
300
|
``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
|
|
301
|
information on the '?' system) to get information about any particular magic
|
|
301
|
information on the '?' system) to get information about any particular magic
|
|
302
|
function you are interested in.
|
|
302
|
function you are interested in.
|
|
303
|
|
|
303
|
|
|
304
|
The API documentation for the :mod:`IPython.core.magic` module contains the full
|
|
304
|
The API documentation for the :mod:`IPython.core.magic` module contains the full
|
|
305
|
docstrings of all currently available magic commands.
|
|
305
|
docstrings of all currently available magic commands.
|
|
306
|
|
|
306
|
|
|
307
|
|
|
307
|
|
|
308
|
Access to the standard Python help
|
|
308
|
Access to the standard Python help
|
|
309
|
----------------------------------
|
|
309
|
----------------------------------
|
|
310
|
|
|
310
|
|
|
311
|
Simply type ``help()`` to access Python's standard help system. You can
|
|
311
|
Simply type ``help()`` to access Python's standard help system. You can
|
|
312
|
also type ``help(object)`` for information about a given object, or
|
|
312
|
also type ``help(object)`` for information about a given object, or
|
|
313
|
``help('keyword')`` for information on a keyword. You may need to configure your
|
|
313
|
``help('keyword')`` for information on a keyword. You may need to configure your
|
|
314
|
PYTHONDOCS environment variable for this feature to work correctly.
|
|
314
|
PYTHONDOCS environment variable for this feature to work correctly.
|
|
315
|
|
|
315
|
|
|
316
|
.. _dynamic_object_info:
|
|
316
|
.. _dynamic_object_info:
|
|
317
|
|
|
317
|
|
|
318
|
Dynamic object information
|
|
318
|
Dynamic object information
|
|
319
|
--------------------------
|
|
319
|
--------------------------
|
|
320
|
|
|
320
|
|
|
321
|
Typing ``?word`` or ``word?`` prints detailed information about an object. If
|
|
321
|
Typing ``?word`` or ``word?`` prints detailed information about an object. If
|
|
322
|
certain strings in the object are too long (e.g. function signatures) they get
|
|
322
|
certain strings in the object are too long (e.g. function signatures) they get
|
|
323
|
snipped in the center for brevity. This system gives access variable types and
|
|
323
|
snipped in the center for brevity. This system gives access variable types and
|
|
324
|
values, docstrings, function prototypes and other useful information.
|
|
324
|
values, docstrings, function prototypes and other useful information.
|
|
325
|
|
|
325
|
|
|
326
|
If the information will not fit in the terminal, it is displayed in a pager
|
|
326
|
If the information will not fit in the terminal, it is displayed in a pager
|
|
327
|
(``less`` if available, otherwise a basic internal pager).
|
|
327
|
(``less`` if available, otherwise a basic internal pager).
|
|
328
|
|
|
328
|
|
|
329
|
Typing ``??word`` or ``word??`` gives access to the full information, including
|
|
329
|
Typing ``??word`` or ``word??`` gives access to the full information, including
|
|
330
|
the source code where possible. Long strings are not snipped.
|
|
330
|
the source code where possible. Long strings are not snipped.
|
|
331
|
|
|
331
|
|
|
332
|
The following magic functions are particularly useful for gathering
|
|
332
|
The following magic functions are particularly useful for gathering
|
|
333
|
information about your working environment. You can get more details by
|
|
333
|
information about your working environment. You can get more details by
|
|
334
|
typing ``%magic`` or querying them individually (``%function_name?``);
|
|
334
|
typing ``%magic`` or querying them individually (``%function_name?``);
|
|
335
|
this is just a summary:
|
|
335
|
this is just a summary:
|
|
336
|
|
|
336
|
|
|
337
|
* **%pdoc <object>**: Print (or run through a pager if too long) the
|
|
337
|
* **%pdoc <object>**: Print (or run through a pager if too long) the
|
|
338
|
docstring for an object. If the given object is a class, it will
|
|
338
|
docstring for an object. If the given object is a class, it will
|
|
339
|
print both the class and the constructor docstrings.
|
|
339
|
print both the class and the constructor docstrings.
|
|
340
|
* **%pdef <object>**: Print the call signature for any callable
|
|
340
|
* **%pdef <object>**: Print the call signature for any callable
|
|
341
|
object. If the object is a class, print the constructor information.
|
|
341
|
object. If the object is a class, print the constructor information.
|
|
342
|
* **%psource <object>**: Print (or run through a pager if too long)
|
|
342
|
* **%psource <object>**: Print (or run through a pager if too long)
|
|
343
|
the source code for an object.
|
|
343
|
the source code for an object.
|
|
344
|
* **%pfile <object>**: Show the entire source file where an object was
|
|
344
|
* **%pfile <object>**: Show the entire source file where an object was
|
|
345
|
defined via a pager, opening it at the line where the object
|
|
345
|
defined via a pager, opening it at the line where the object
|
|
346
|
definition begins.
|
|
346
|
definition begins.
|
|
347
|
* **%who/%whos**: These functions give information about identifiers
|
|
347
|
* **%who/%whos**: These functions give information about identifiers
|
|
348
|
you have defined interactively (not things you loaded or defined
|
|
348
|
you have defined interactively (not things you loaded or defined
|
|
349
|
in your configuration files). %who just prints a list of
|
|
349
|
in your configuration files). %who just prints a list of
|
|
350
|
identifiers and %whos prints a table with some basic details about
|
|
350
|
identifiers and %whos prints a table with some basic details about
|
|
351
|
each identifier.
|
|
351
|
each identifier.
|
|
352
|
|
|
352
|
|
|
353
|
Note that the dynamic object information functions (?/??, ``%pdoc``,
|
|
353
|
Note that the dynamic object information functions (?/??, ``%pdoc``,
|
|
354
|
``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
|
|
354
|
``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
|
|
355
|
directly on variables. For example, after doing ``import os``, you can use
|
|
355
|
directly on variables. For example, after doing ``import os``, you can use
|
|
356
|
``os.path.abspath??``.
|
|
356
|
``os.path.abspath??``.
|
|
357
|
|
|
357
|
|
|
358
|
.. _readline:
|
|
358
|
.. _readline:
|
|
359
|
|
|
359
|
|
|
360
|
Readline-based features
|
|
360
|
Readline-based features
|
|
361
|
-----------------------
|
|
361
|
-----------------------
|
|
362
|
|
|
362
|
|
|
363
|
These features require the GNU readline library, so they won't work if your
|
|
363
|
These features require the GNU readline library, so they won't work if your
|
|
364
|
Python installation lacks readline support. We will first describe the default
|
|
364
|
Python installation lacks readline support. We will first describe the default
|
|
365
|
behavior IPython uses, and then how to change it to suit your preferences.
|
|
365
|
behavior IPython uses, and then how to change it to suit your preferences.
|
|
366
|
|
|
366
|
|
|
367
|
|
|
367
|
|
|
368
|
Command line completion
|
|
368
|
Command line completion
|
|
369
|
+++++++++++++++++++++++
|
|
369
|
+++++++++++++++++++++++
|
|
370
|
|
|
370
|
|
|
371
|
At any time, hitting TAB will complete any available python commands or
|
|
371
|
At any time, hitting TAB will complete any available python commands or
|
|
372
|
variable names, and show you a list of the possible completions if
|
|
372
|
variable names, and show you a list of the possible completions if
|
|
373
|
there's no unambiguous one. It will also complete filenames in the
|
|
373
|
there's no unambiguous one. It will also complete filenames in the
|
|
374
|
current directory if no python names match what you've typed so far.
|
|
374
|
current directory if no python names match what you've typed so far.
|
|
375
|
|
|
375
|
|
|
376
|
|
|
376
|
|
|
377
|
Search command history
|
|
377
|
Search command history
|
|
378
|
++++++++++++++++++++++
|
|
378
|
++++++++++++++++++++++
|
|
379
|
|
|
379
|
|
|
380
|
IPython provides two ways for searching through previous input and thus
|
|
380
|
IPython provides two ways for searching through previous input and thus
|
|
381
|
reduce the need for repetitive typing:
|
|
381
|
reduce the need for repetitive typing:
|
|
382
|
|
|
382
|
|
|
383
|
1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
|
|
383
|
1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
|
|
384
|
(next,down) to search through only the history items that match
|
|
384
|
(next,down) to search through only the history items that match
|
|
385
|
what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
|
|
385
|
what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
|
|
386
|
prompt, they just behave like normal arrow keys.
|
|
386
|
prompt, they just behave like normal arrow keys.
|
|
387
|
2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
|
|
387
|
2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
|
|
388
|
searches your history for lines that contain what you've typed so
|
|
388
|
searches your history for lines that contain what you've typed so
|
|
389
|
far, completing as much as it can.
|
|
389
|
far, completing as much as it can.
|
|
390
|
|
|
390
|
|
|
391
|
|
|
391
|
|
|
392
|
Persistent command history across sessions
|
|
392
|
Persistent command history across sessions
|
|
393
|
++++++++++++++++++++++++++++++++++++++++++
|
|
393
|
++++++++++++++++++++++++++++++++++++++++++
|
|
394
|
|
|
394
|
|
|
395
|
IPython will save your input history when it leaves and reload it next
|
|
395
|
IPython will save your input history when it leaves and reload it next
|
|
396
|
time you restart it. By default, the history file is named
|
|
396
|
time you restart it. By default, the history file is named
|
|
397
|
$IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
|
|
397
|
$IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
|
|
398
|
separate histories related to various tasks: commands related to
|
|
398
|
separate histories related to various tasks: commands related to
|
|
399
|
numerical work will not be clobbered by a system shell history, for
|
|
399
|
numerical work will not be clobbered by a system shell history, for
|
|
400
|
example.
|
|
400
|
example.
|
|
401
|
|
|
401
|
|
|
402
|
|
|
402
|
|
|
403
|
Autoindent
|
|
403
|
Autoindent
|
|
404
|
++++++++++
|
|
404
|
++++++++++
|
|
405
|
|
|
405
|
|
|
406
|
IPython can recognize lines ending in ':' and indent the next line,
|
|
406
|
IPython can recognize lines ending in ':' and indent the next line,
|
|
407
|
while also un-indenting automatically after 'raise' or 'return'.
|
|
407
|
while also un-indenting automatically after 'raise' or 'return'.
|
|
408
|
|
|
408
|
|
|
409
|
This feature uses the readline library, so it will honor your
|
|
409
|
This feature uses the readline library, so it will honor your
|
|
410
|
:file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
|
|
410
|
:file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
|
|
411
|
to). Adding the following lines to your :file:`.inputrc` file can make
|
|
411
|
to). Adding the following lines to your :file:`.inputrc` file can make
|
|
412
|
indenting/unindenting more convenient (M-i indents, M-u unindents)::
|
|
412
|
indenting/unindenting more convenient (M-i indents, M-u unindents)::
|
|
413
|
|
|
413
|
|
|
414
|
$if Python
|
|
414
|
$if Python
|
|
415
|
"\M-i": " "
|
|
415
|
"\M-i": " "
|
|
416
|
"\M-u": "\d\d\d\d"
|
|
416
|
"\M-u": "\d\d\d\d"
|
|
417
|
$endif
|
|
417
|
$endif
|
|
418
|
|
|
418
|
|
|
419
|
Note that there are 4 spaces between the quote marks after "M-i" above.
|
|
419
|
Note that there are 4 spaces between the quote marks after "M-i" above.
|
|
420
|
|
|
420
|
|
|
421
|
.. warning::
|
|
421
|
.. warning::
|
|
422
|
|
|
422
|
|
|
423
|
Setting the above indents will cause problems with unicode text entry in
|
|
423
|
Setting the above indents will cause problems with unicode text entry in
|
|
424
|
the terminal.
|
|
424
|
the terminal.
|
|
425
|
|
|
425
|
|
|
426
|
.. warning::
|
|
426
|
.. warning::
|
|
427
|
|
|
427
|
|
|
428
|
Autoindent is ON by default, but it can cause problems with the pasting of
|
|
428
|
Autoindent is ON by default, but it can cause problems with the pasting of
|
|
429
|
multi-line indented code (the pasted code gets re-indented on each line). A
|
|
429
|
multi-line indented code (the pasted code gets re-indented on each line). A
|
|
430
|
magic function %autoindent allows you to toggle it on/off at runtime. You
|
|
430
|
magic function %autoindent allows you to toggle it on/off at runtime. You
|
|
431
|
can also disable it permanently on in your :file:`ipython_config.py` file
|
|
431
|
can also disable it permanently on in your :file:`ipython_config.py` file
|
|
432
|
(set TerminalInteractiveShell.autoindent=False).
|
|
432
|
(set TerminalInteractiveShell.autoindent=False).
|
|
433
|
|
|
433
|
|
|
434
|
If you want to paste multiple lines in the terminal, it is recommended that
|
|
434
|
If you want to paste multiple lines in the terminal, it is recommended that
|
|
435
|
you use ``%paste``.
|
|
435
|
you use ``%paste``.
|
|
436
|
|
|
436
|
|
|
437
|
|
|
437
|
|
|
438
|
Customizing readline behavior
|
|
438
|
Customizing readline behavior
|
|
439
|
+++++++++++++++++++++++++++++
|
|
439
|
+++++++++++++++++++++++++++++
|
|
440
|
|
|
440
|
|
|
441
|
All these features are based on the GNU readline library, which has an
|
|
441
|
All these features are based on the GNU readline library, which has an
|
|
442
|
extremely customizable interface. Normally, readline is configured via a
|
|
442
|
extremely customizable interface. Normally, readline is configured via a
|
|
443
|
file which defines the behavior of the library; the details of the
|
|
443
|
file which defines the behavior of the library; the details of the
|
|
444
|
syntax for this can be found in the readline documentation available
|
|
444
|
syntax for this can be found in the readline documentation available
|
|
445
|
with your system or on the Internet. IPython doesn't read this file (if
|
|
445
|
with your system or on the Internet. IPython doesn't read this file (if
|
|
446
|
it exists) directly, but it does support passing to readline valid
|
|
446
|
it exists) directly, but it does support passing to readline valid
|
|
447
|
options via a simple interface. In brief, you can customize readline by
|
|
447
|
options via a simple interface. In brief, you can customize readline by
|
|
448
|
setting the following options in your configuration file (note
|
|
448
|
setting the following options in your configuration file (note
|
|
449
|
that these options can not be specified at the command line):
|
|
449
|
that these options can not be specified at the command line):
|
|
450
|
|
|
450
|
|
|
451
|
* **readline_parse_and_bind**: this holds a list of strings to be executed
|
|
451
|
* **readline_parse_and_bind**: this holds a list of strings to be executed
|
|
452
|
via a readline.parse_and_bind() command. The syntax for valid commands
|
|
452
|
via a readline.parse_and_bind() command. The syntax for valid commands
|
|
453
|
of this kind can be found by reading the documentation for the GNU
|
|
453
|
of this kind can be found by reading the documentation for the GNU
|
|
454
|
readline library, as these commands are of the kind which readline
|
|
454
|
readline library, as these commands are of the kind which readline
|
|
455
|
accepts in its configuration file.
|
|
455
|
accepts in its configuration file.
|
|
456
|
* **readline_remove_delims**: a string of characters to be removed
|
|
456
|
* **readline_remove_delims**: a string of characters to be removed
|
|
457
|
from the default word-delimiters list used by readline, so that
|
|
457
|
from the default word-delimiters list used by readline, so that
|
|
458
|
completions may be performed on strings which contain them. Do not
|
|
458
|
completions may be performed on strings which contain them. Do not
|
|
459
|
change the default value unless you know what you're doing.
|
|
459
|
change the default value unless you know what you're doing.
|
|
460
|
|
|
460
|
|
|
461
|
You will find the default values in your configuration file.
|
|
461
|
You will find the default values in your configuration file.
|
|
462
|
|
|
462
|
|
|
463
|
|
|
463
|
|
|
464
|
Session logging and restoring
|
|
464
|
Session logging and restoring
|
|
465
|
-----------------------------
|
|
465
|
-----------------------------
|
|
466
|
|
|
466
|
|
|
467
|
You can log all input from a session either by starting IPython with the
|
|
467
|
You can log all input from a session either by starting IPython with the
|
|
468
|
command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
|
|
468
|
command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
|
|
469
|
or by activating the logging at any moment with the magic function %logstart.
|
|
469
|
or by activating the logging at any moment with the magic function %logstart.
|
|
470
|
|
|
470
|
|
|
471
|
Log files can later be reloaded by running them as scripts and IPython
|
|
471
|
Log files can later be reloaded by running them as scripts and IPython
|
|
472
|
will attempt to 'replay' the log by executing all the lines in it, thus
|
|
472
|
will attempt to 'replay' the log by executing all the lines in it, thus
|
|
473
|
restoring the state of a previous session. This feature is not quite
|
|
473
|
restoring the state of a previous session. This feature is not quite
|
|
474
|
perfect, but can still be useful in many cases.
|
|
474
|
perfect, but can still be useful in many cases.
|
|
475
|
|
|
475
|
|
|
476
|
The log files can also be used as a way to have a permanent record of
|
|
476
|
The log files can also be used as a way to have a permanent record of
|
|
477
|
any code you wrote while experimenting. Log files are regular text files
|
|
477
|
any code you wrote while experimenting. Log files are regular text files
|
|
478
|
which you can later open in your favorite text editor to extract code or
|
|
478
|
which you can later open in your favorite text editor to extract code or
|
|
479
|
to 'clean them up' before using them to replay a session.
|
|
479
|
to 'clean them up' before using them to replay a session.
|
|
480
|
|
|
480
|
|
|
481
|
The `%logstart` function for activating logging in mid-session is used as
|
|
481
|
The `%logstart` function for activating logging in mid-session is used as
|
|
482
|
follows::
|
|
482
|
follows::
|
|
483
|
|
|
483
|
|
|
484
|
%logstart [log_name [log_mode]]
|
|
484
|
%logstart [log_name [log_mode]]
|
|
485
|
|
|
485
|
|
|
486
|
If no name is given, it defaults to a file named 'ipython_log.py' in your
|
|
486
|
If no name is given, it defaults to a file named 'ipython_log.py' in your
|
|
487
|
current working directory, in 'rotate' mode (see below).
|
|
487
|
current working directory, in 'rotate' mode (see below).
|
|
488
|
|
|
488
|
|
|
489
|
'%logstart name' saves to file 'name' in 'backup' mode. It saves your
|
|
489
|
'%logstart name' saves to file 'name' in 'backup' mode. It saves your
|
|
490
|
history up to that point and then continues logging.
|
|
490
|
history up to that point and then continues logging.
|
|
491
|
|
|
491
|
|
|
492
|
%logstart takes a second optional parameter: logging mode. This can be
|
|
492
|
%logstart takes a second optional parameter: logging mode. This can be
|
|
493
|
one of (note that the modes are given unquoted):
|
|
493
|
one of (note that the modes are given unquoted):
|
|
494
|
|
|
494
|
|
|
495
|
* [over:] overwrite existing log_name.
|
|
495
|
* [over:] overwrite existing log_name.
|
|
496
|
* [backup:] rename (if exists) to log_name~ and start log_name.
|
|
496
|
* [backup:] rename (if exists) to log_name~ and start log_name.
|
|
497
|
* [append:] well, that says it.
|
|
497
|
* [append:] well, that says it.
|
|
498
|
* [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
|
|
498
|
* [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
|
|
499
|
|
|
499
|
|
|
500
|
The %logoff and %logon functions allow you to temporarily stop and
|
|
500
|
The %logoff and %logon functions allow you to temporarily stop and
|
|
501
|
resume logging to a file which had previously been started with
|
|
501
|
resume logging to a file which had previously been started with
|
|
502
|
%logstart. They will fail (with an explanation) if you try to use them
|
|
502
|
%logstart. They will fail (with an explanation) if you try to use them
|
|
503
|
before logging has been started.
|
|
503
|
before logging has been started.
|
|
504
|
|
|
504
|
|
|
505
|
.. _system_shell_access:
|
|
505
|
.. _system_shell_access:
|
|
506
|
|
|
506
|
|
|
507
|
System shell access
|
|
507
|
System shell access
|
|
508
|
-------------------
|
|
508
|
-------------------
|
|
509
|
|
|
509
|
|
|
510
|
Any input line beginning with a ! character is passed verbatim (minus
|
|
510
|
Any input line beginning with a ! character is passed verbatim (minus
|
|
511
|
the !, of course) to the underlying operating system. For example,
|
|
511
|
the !, of course) to the underlying operating system. For example,
|
|
512
|
typing ``!ls`` will run 'ls' in the current directory.
|
|
512
|
typing ``!ls`` will run 'ls' in the current directory.
|
|
513
|
|
|
513
|
|
|
514
|
Manual capture of command output
|
|
514
|
Manual capture of command output
|
|
515
|
--------------------------------
|
|
515
|
--------------------------------
|
|
516
|
|
|
516
|
|
|
517
|
You can assign the result of a system command to a Python variable with the
|
|
517
|
You can assign the result of a system command to a Python variable with the
|
|
518
|
syntax ``myfiles = !ls``. This gets machine readable output from stdout
|
|
518
|
syntax ``myfiles = !ls``. This gets machine readable output from stdout
|
|
519
|
(e.g. without colours), and splits on newlines. To explicitly get this sort of
|
|
519
|
(e.g. without colours), and splits on newlines. To explicitly get this sort of
|
|
520
|
output without assigning to a variable, use two exclamation marks (``!!ls``) or
|
|
520
|
output without assigning to a variable, use two exclamation marks (``!!ls``) or
|
|
521
|
the ``%sx`` magic command.
|
|
521
|
the ``%sx`` magic command.
|
|
522
|
|
|
522
|
|
|
523
|
The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
|
|
523
|
The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
|
|
524
|
returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
|
|
524
|
returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
|
|
525
|
produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
|
|
525
|
produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
|
|
526
|
See :ref:`string_lists` for details.
|
|
526
|
See :ref:`string_lists` for details.
|
|
527
|
|
|
527
|
|
|
528
|
IPython also allows you to expand the value of python variables when
|
|
528
|
IPython also allows you to expand the value of python variables when
|
|
529
|
making system calls. Wrap variables or expressions in {braces}::
|
|
529
|
making system calls. Wrap variables or expressions in {braces}::
|
|
530
|
|
|
530
|
|
|
531
|
In [1]: pyvar = 'Hello world'
|
|
531
|
In [1]: pyvar = 'Hello world'
|
|
532
|
In [2]: !echo "A python variable: {pyvar}"
|
|
532
|
In [2]: !echo "A python variable: {pyvar}"
|
|
533
|
A python variable: Hello world
|
|
533
|
A python variable: Hello world
|
|
534
|
In [3]: import math
|
|
534
|
In [3]: import math
|
|
535
|
In [4]: x = 8
|
|
535
|
In [4]: x = 8
|
|
536
|
In [5]: !echo {math.factorial(x)}
|
|
536
|
In [5]: !echo {math.factorial(x)}
|
|
537
|
40320
|
|
537
|
40320
|
|
538
|
|
|
538
|
|
|
539
|
For simple cases, you can alternatively prepend $ to a variable name::
|
|
539
|
For simple cases, you can alternatively prepend $ to a variable name::
|
|
540
|
|
|
540
|
|
|
541
|
In [6]: !echo $sys.argv
|
|
541
|
In [6]: !echo $sys.argv
|
|
542
|
[/home/fperez/usr/bin/ipython]
|
|
542
|
[/home/fperez/usr/bin/ipython]
|
|
543
|
In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
|
|
543
|
In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
|
|
544
|
A system variable: /home/fperez
|
|
544
|
A system variable: /home/fperez
|
|
545
|
|
|
545
|
|
|
546
|
System command aliases
|
|
546
|
System command aliases
|
|
547
|
----------------------
|
|
547
|
----------------------
|
|
548
|
|
|
548
|
|
|
549
|
The %alias magic function allows you to define magic functions which are in fact
|
|
549
|
The %alias magic function allows you to define magic functions which are in fact
|
|
550
|
system shell commands. These aliases can have parameters.
|
|
550
|
system shell commands. These aliases can have parameters.
|
|
551
|
|
|
551
|
|
|
552
|
``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
|
|
552
|
``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
|
|
553
|
|
|
553
|
|
|
554
|
Then, typing ``alias_name params`` will execute the system command 'cmd
|
|
554
|
Then, typing ``alias_name params`` will execute the system command 'cmd
|
|
555
|
params' (from your underlying operating system).
|
|
555
|
params' (from your underlying operating system).
|
|
556
|
|
|
556
|
|
|
557
|
You can also define aliases with parameters using %s specifiers (one per
|
|
557
|
You can also define aliases with parameters using %s specifiers (one per
|
|
558
|
parameter). The following example defines the parts function as an
|
|
558
|
parameter). The following example defines the parts function as an
|
|
559
|
alias to the command 'echo first %s second %s' where each %s will be
|
|
559
|
alias to the command 'echo first %s second %s' where each %s will be
|
|
560
|
replaced by a positional parameter to the call to %parts::
|
|
560
|
replaced by a positional parameter to the call to %parts::
|
|
561
|
|
|
561
|
|
|
562
|
In [1]: %alias parts echo first %s second %s
|
|
562
|
In [1]: %alias parts echo first %s second %s
|
|
563
|
In [2]: parts A B
|
|
563
|
In [2]: parts A B
|
|
564
|
first A second B
|
|
564
|
first A second B
|
|
565
|
In [3]: parts A
|
|
565
|
In [3]: parts A
|
|
566
|
ERROR: Alias <parts> requires 2 arguments, 1 given.
|
|
566
|
ERROR: Alias <parts> requires 2 arguments, 1 given.
|
|
567
|
|
|
567
|
|
|
568
|
If called with no parameters, %alias prints the table of currently
|
|
568
|
If called with no parameters, %alias prints the table of currently
|
|
569
|
defined aliases.
|
|
569
|
defined aliases.
|
|
570
|
|
|
570
|
|
|
571
|
The %rehashx magic allows you to load your entire $PATH as
|
|
571
|
The %rehashx magic allows you to load your entire $PATH as
|
|
572
|
ipython aliases. See its docstring for further details.
|
|
572
|
ipython aliases. See its docstring for further details.
|
|
573
|
|
|
573
|
|
|
574
|
|
|
574
|
|
|
575
|
.. _dreload:
|
|
575
|
.. _dreload:
|
|
576
|
|
|
576
|
|
|
577
|
Recursive reload
|
|
577
|
Recursive reload
|
|
578
|
----------------
|
|
578
|
----------------
|
|
579
|
|
|
579
|
|
|
580
|
The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
|
|
580
|
The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
|
|
581
|
module: changes made to any of its dependencies will be reloaded without
|
|
581
|
module: changes made to any of its dependencies will be reloaded without
|
|
582
|
having to exit. To start using it, do::
|
|
582
|
having to exit. To start using it, do::
|
|
583
|
|
|
583
|
|
|
584
|
from IPython.lib.deepreload import reload as dreload
|
|
584
|
from IPython.lib.deepreload import reload as dreload
|
|
585
|
|
|
585
|
|
|
586
|
|
|
586
|
|
|
587
|
Verbose and colored exception traceback printouts
|
|
587
|
Verbose and colored exception traceback printouts
|
|
588
|
-------------------------------------------------
|
|
588
|
-------------------------------------------------
|
|
589
|
|
|
589
|
|
|
590
|
IPython provides the option to see very detailed exception tracebacks,
|
|
590
|
IPython provides the option to see very detailed exception tracebacks,
|
|
591
|
which can be especially useful when debugging large programs. You can
|
|
591
|
which can be especially useful when debugging large programs. You can
|
|
592
|
run any Python file with the %run function to benefit from these
|
|
592
|
run any Python file with the %run function to benefit from these
|
|
593
|
detailed tracebacks. Furthermore, both normal and verbose tracebacks can
|
|
593
|
detailed tracebacks. Furthermore, both normal and verbose tracebacks can
|
|
594
|
be colored (if your terminal supports it) which makes them much easier
|
|
594
|
be colored (if your terminal supports it) which makes them much easier
|
|
595
|
to parse visually.
|
|
595
|
to parse visually.
|
|
596
|
|
|
596
|
|
|
597
|
See the magic xmode and colors functions for details (just type %magic).
|
|
597
|
See the magic xmode and colors functions for details (just type %magic).
|
|
598
|
|
|
598
|
|
|
599
|
These features are basically a terminal version of Ka-Ping Yee's cgitb
|
|
599
|
These features are basically a terminal version of Ka-Ping Yee's cgitb
|
|
600
|
module, now part of the standard Python library.
|
|
600
|
module, now part of the standard Python library.
|
|
601
|
|
|
601
|
|
|
602
|
|
|
602
|
|
|
603
|
.. _input_caching:
|
|
603
|
.. _input_caching:
|
|
604
|
|
|
604
|
|
|
605
|
Input caching system
|
|
605
|
Input caching system
|
|
606
|
--------------------
|
|
606
|
--------------------
|
|
607
|
|
|
607
|
|
|
608
|
IPython offers numbered prompts (In/Out) with input and output caching
|
|
608
|
IPython offers numbered prompts (In/Out) with input and output caching
|
|
609
|
(also referred to as 'input history'). All input is saved and can be
|
|
609
|
(also referred to as 'input history'). All input is saved and can be
|
|
610
|
retrieved as variables (besides the usual arrow key recall), in
|
|
610
|
retrieved as variables (besides the usual arrow key recall), in
|
|
611
|
addition to the %rep magic command that brings a history entry
|
|
611
|
addition to the %rep magic command that brings a history entry
|
|
612
|
up for editing on the next command line.
|
|
612
|
up for editing on the next command line.
|
|
613
|
|
|
613
|
|
|
614
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
614
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
615
|
|
|
615
|
|
|
616
|
* _i, _ii, _iii: store previous, next previous and next-next previous inputs.
|
|
616
|
* _i, _ii, _iii: store previous, next previous and next-next previous inputs.
|
|
617
|
* In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
|
|
617
|
* In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
|
|
618
|
overwrite In with a variable of your own, you can remake the assignment to the
|
|
618
|
overwrite In with a variable of your own, you can remake the assignment to the
|
|
619
|
internal list with a simple ``In=_ih``.
|
|
619
|
internal list with a simple ``In=_ih``.
|
|
620
|
|
|
620
|
|
|
621
|
Additionally, global variables named _i<n> are dynamically created (<n>
|
|
621
|
Additionally, global variables named _i<n> are dynamically created (<n>
|
|
622
|
being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
|
|
622
|
being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
|
|
623
|
|
|
623
|
|
|
624
|
For example, what you typed at prompt 14 is available as _i14, _ih[14]
|
|
624
|
For example, what you typed at prompt 14 is available as _i14, _ih[14]
|
|
625
|
and In[14].
|
|
625
|
and In[14].
|
|
626
|
|
|
626
|
|
|
627
|
This allows you to easily cut and paste multi line interactive prompts
|
|
627
|
This allows you to easily cut and paste multi line interactive prompts
|
|
628
|
by printing them out: they print like a clean string, without prompt
|
|
628
|
by printing them out: they print like a clean string, without prompt
|
|
629
|
characters. You can also manipulate them like regular variables (they
|
|
629
|
characters. You can also manipulate them like regular variables (they
|
|
630
|
are strings), modify or exec them (typing ``exec _i9`` will re-execute the
|
|
630
|
are strings), modify or exec them (typing ``exec _i9`` will re-execute the
|
|
631
|
contents of input prompt 9.
|
|
631
|
contents of input prompt 9.
|
|
632
|
|
|
632
|
|
|
633
|
You can also re-execute multiple lines of input easily by using the
|
|
633
|
You can also re-execute multiple lines of input easily by using the
|
|
634
|
magic %rerun or %macro functions. The macro system also allows you to re-execute
|
|
634
|
magic %rerun or %macro functions. The macro system also allows you to re-execute
|
|
635
|
previous lines which include magic function calls (which require special
|
|
635
|
previous lines which include magic function calls (which require special
|
|
636
|
processing). Type %macro? for more details on the macro system.
|
|
636
|
processing). Type %macro? for more details on the macro system.
|
|
637
|
|
|
637
|
|
|
638
|
A history function %hist allows you to see any part of your input
|
|
638
|
A history function %hist allows you to see any part of your input
|
|
639
|
history by printing a range of the _i variables.
|
|
639
|
history by printing a range of the _i variables.
|
|
640
|
|
|
640
|
|
|
641
|
You can also search ('grep') through your history by typing
|
|
641
|
You can also search ('grep') through your history by typing
|
|
642
|
``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
|
|
642
|
``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
|
|
643
|
etc. You can bring history entries listed by '%hist -g' up for editing
|
|
643
|
etc. You can bring history entries listed by '%hist -g' up for editing
|
|
644
|
with the %recall command, or run them immediately with %rerun.
|
|
644
|
with the %recall command, or run them immediately with %rerun.
|
|
645
|
|
|
645
|
|
|
646
|
.. _output_caching:
|
|
646
|
.. _output_caching:
|
|
647
|
|
|
647
|
|
|
648
|
Output caching system
|
|
648
|
Output caching system
|
|
649
|
---------------------
|
|
649
|
---------------------
|
|
650
|
|
|
650
|
|
|
651
|
For output that is returned from actions, a system similar to the input
|
|
651
|
For output that is returned from actions, a system similar to the input
|
|
652
|
cache exists but using _ instead of _i. Only actions that produce a
|
|
652
|
cache exists but using _ instead of _i. Only actions that produce a
|
|
653
|
result (NOT assignments, for example) are cached. If you are familiar
|
|
653
|
result (NOT assignments, for example) are cached. If you are familiar
|
|
654
|
with Mathematica, IPython's _ variables behave exactly like
|
|
654
|
with Mathematica, IPython's _ variables behave exactly like
|
|
655
|
Mathematica's % variables.
|
|
655
|
Mathematica's % variables.
|
|
656
|
|
|
656
|
|
|
657
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
657
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
658
|
|
|
658
|
|
|
659
|
* [_] (a single underscore) : stores previous output, like Python's
|
|
659
|
* [_] (a single underscore) : stores previous output, like Python's
|
|
660
|
default interpreter.
|
|
660
|
default interpreter.
|
|
661
|
* [__] (two underscores): next previous.
|
|
661
|
* [__] (two underscores): next previous.
|
|
662
|
* [___] (three underscores): next-next previous.
|
|
662
|
* [___] (three underscores): next-next previous.
|
|
663
|
|
|
663
|
|
|
664
|
Additionally, global variables named _<n> are dynamically created (<n>
|
|
664
|
Additionally, global variables named _<n> are dynamically created (<n>
|
|
665
|
being the prompt counter), such that the result of output <n> is always
|
|
665
|
being the prompt counter), such that the result of output <n> is always
|
|
666
|
available as _<n> (don't use the angle brackets, just the number, e.g.
|
|
666
|
available as _<n> (don't use the angle brackets, just the number, e.g.
|
|
667
|
_21).
|
|
667
|
_21).
|
|
668
|
|
|
668
|
|
|
669
|
These variables are also stored in a global dictionary (not a
|
|
669
|
These variables are also stored in a global dictionary (not a
|
|
670
|
list, since it only has entries for lines which returned a result)
|
|
670
|
list, since it only has entries for lines which returned a result)
|
|
671
|
available under the names _oh and Out (similar to _ih and In). So the
|
|
671
|
available under the names _oh and Out (similar to _ih and In). So the
|
|
672
|
output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
|
|
672
|
output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
|
|
673
|
accidentally overwrite the Out variable you can recover it by typing
|
|
673
|
accidentally overwrite the Out variable you can recover it by typing
|
|
674
|
'Out=_oh' at the prompt.
|
|
674
|
'Out=_oh' at the prompt.
|
|
675
|
|
|
675
|
|
|
676
|
This system obviously can potentially put heavy memory demands on your
|
|
676
|
This system obviously can potentially put heavy memory demands on your
|
|
677
|
system, since it prevents Python's garbage collector from removing any
|
|
677
|
system, since it prevents Python's garbage collector from removing any
|
|
678
|
previously computed results. You can control how many results are kept
|
|
678
|
previously computed results. You can control how many results are kept
|
|
679
|
in memory with the option (at the command line or in your configuration
|
|
679
|
in memory with the option (at the command line or in your configuration
|
|
680
|
file) cache_size. If you set it to 0, the whole system is completely
|
|
680
|
file) cache_size. If you set it to 0, the whole system is completely
|
|
681
|
disabled and the prompts revert to the classic '>>>' of normal Python.
|
|
681
|
disabled and the prompts revert to the classic '>>>' of normal Python.
|
|
682
|
|
|
682
|
|
|
683
|
|
|
683
|
|
|
684
|
Directory history
|
|
684
|
Directory history
|
|
685
|
-----------------
|
|
685
|
-----------------
|
|
686
|
|
|
686
|
|
|
687
|
Your history of visited directories is kept in the global list _dh, and
|
|
687
|
Your history of visited directories is kept in the global list _dh, and
|
|
688
|
the magic %cd command can be used to go to any entry in that list. The
|
|
688
|
the magic %cd command can be used to go to any entry in that list. The
|
|
689
|
%dhist command allows you to view this history. Do ``cd -<TAB>`` to
|
|
689
|
%dhist command allows you to view this history. Do ``cd -<TAB>`` to
|
|
690
|
conveniently view the directory history.
|
|
690
|
conveniently view the directory history.
|
|
691
|
|
|
691
|
|
|
692
|
|
|
692
|
|
|
693
|
Automatic parentheses and quotes
|
|
693
|
Automatic parentheses and quotes
|
|
694
|
--------------------------------
|
|
694
|
--------------------------------
|
|
695
|
|
|
695
|
|
|
696
|
These features were adapted from Nathan Gray's LazyPython. They are
|
|
696
|
These features were adapted from Nathan Gray's LazyPython. They are
|
|
697
|
meant to allow less typing for common situations.
|
|
697
|
meant to allow less typing for common situations.
|
|
698
|
|
|
698
|
|
|
699
|
|
|
699
|
|
|
700
|
Automatic parentheses
|
|
700
|
Automatic parentheses
|
|
701
|
+++++++++++++++++++++
|
|
701
|
+++++++++++++++++++++
|
|
702
|
|
|
702
|
|
|
703
|
Callable objects (i.e. functions, methods, etc) can be invoked like this
|
|
703
|
Callable objects (i.e. functions, methods, etc) can be invoked like this
|
|
704
|
(notice the commas between the arguments)::
|
|
704
|
(notice the commas between the arguments)::
|
|
705
|
|
|
705
|
|
|
706
|
In [1]: callable_ob arg1, arg2, arg3
|
|
706
|
In [1]: callable_ob arg1, arg2, arg3
|
|
707
|
------> callable_ob(arg1, arg2, arg3)
|
|
707
|
------> callable_ob(arg1, arg2, arg3)
|
|
708
|
|
|
708
|
|
|
709
|
You can force automatic parentheses by using '/' as the first character
|
|
709
|
You can force automatic parentheses by using '/' as the first character
|
|
710
|
of a line. For example::
|
|
710
|
of a line. For example::
|
|
711
|
|
|
711
|
|
|
712
|
In [2]: /globals # becomes 'globals()'
|
|
712
|
In [2]: /globals # becomes 'globals()'
|
|
713
|
|
|
713
|
|
|
714
|
Note that the '/' MUST be the first character on the line! This won't work::
|
|
714
|
Note that the '/' MUST be the first character on the line! This won't work::
|
|
715
|
|
|
715
|
|
|
716
|
In [3]: print /globals # syntax error
|
|
716
|
In [3]: print /globals # syntax error
|
|
717
|
|
|
717
|
|
|
718
|
In most cases the automatic algorithm should work, so you should rarely
|
|
718
|
In most cases the automatic algorithm should work, so you should rarely
|
|
719
|
need to explicitly invoke /. One notable exception is if you are trying
|
|
719
|
need to explicitly invoke /. One notable exception is if you are trying
|
|
720
|
to call a function with a list of tuples as arguments (the parenthesis
|
|
720
|
to call a function with a list of tuples as arguments (the parenthesis
|
|
721
|
will confuse IPython)::
|
|
721
|
will confuse IPython)::
|
|
722
|
|
|
722
|
|
|
723
|
In [4]: zip (1,2,3),(4,5,6) # won't work
|
|
723
|
In [4]: zip (1,2,3),(4,5,6) # won't work
|
|
724
|
|
|
724
|
|
|
725
|
but this will work::
|
|
725
|
but this will work::
|
|
726
|
|
|
726
|
|
|
727
|
In [5]: /zip (1,2,3),(4,5,6)
|
|
727
|
In [5]: /zip (1,2,3),(4,5,6)
|
|
728
|
------> zip ((1,2,3),(4,5,6))
|
|
728
|
------> zip ((1,2,3),(4,5,6))
|
|
729
|
Out[5]: [(1, 4), (2, 5), (3, 6)]
|
|
729
|
Out[5]: [(1, 4), (2, 5), (3, 6)]
|
|
730
|
|
|
730
|
|
|
731
|
IPython tells you that it has altered your command line by displaying
|
|
731
|
IPython tells you that it has altered your command line by displaying
|
|
732
|
the new command line preceded by ->. e.g.::
|
|
732
|
the new command line preceded by ->. e.g.::
|
|
733
|
|
|
733
|
|
|
734
|
In [6]: callable list
|
|
734
|
In [6]: callable list
|
|
735
|
------> callable(list)
|
|
735
|
------> callable(list)
|
|
736
|
|
|
736
|
|
|
737
|
|
|
737
|
|
|
738
|
Automatic quoting
|
|
738
|
Automatic quoting
|
|
739
|
+++++++++++++++++
|
|
739
|
+++++++++++++++++
|
|
740
|
|
|
740
|
|
|
741
|
You can force automatic quoting of a function's arguments by using ','
|
|
741
|
You can force automatic quoting of a function's arguments by using ','
|
|
742
|
or ';' as the first character of a line. For example::
|
|
742
|
or ';' as the first character of a line. For example::
|
|
743
|
|
|
743
|
|
|
744
|
In [1]: ,my_function /home/me # becomes my_function("/home/me")
|
|
744
|
In [1]: ,my_function /home/me # becomes my_function("/home/me")
|
|
745
|
|
|
745
|
|
|
746
|
If you use ';' the whole argument is quoted as a single string, while ',' splits
|
|
746
|
If you use ';' the whole argument is quoted as a single string, while ',' splits
|
|
747
|
on whitespace::
|
|
747
|
on whitespace::
|
|
748
|
|
|
748
|
|
|
749
|
In [2]: ,my_function a b c # becomes my_function("a","b","c")
|
|
749
|
In [2]: ,my_function a b c # becomes my_function("a","b","c")
|
|
750
|
|
|
750
|
|
|
751
|
In [3]: ;my_function a b c # becomes my_function("a b c")
|
|
751
|
In [3]: ;my_function a b c # becomes my_function("a b c")
|
|
752
|
|
|
752
|
|
|
753
|
Note that the ',' or ';' MUST be the first character on the line! This
|
|
753
|
Note that the ',' or ';' MUST be the first character on the line! This
|
|
754
|
won't work::
|
|
754
|
won't work::
|
|
755
|
|
|
755
|
|
|
756
|
In [4]: x = ,my_function /home/me # syntax error
|
|
756
|
In [4]: x = ,my_function /home/me # syntax error
|
|
757
|
|
|
757
|
|
|
758
|
IPython as your default Python environment
|
|
758
|
IPython as your default Python environment
|
|
759
|
==========================================
|
|
759
|
==========================================
|
|
760
|
|
|
760
|
|
|
761
|
Python honors the environment variable PYTHONSTARTUP and will execute at
|
|
761
|
Python honors the environment variable PYTHONSTARTUP and will execute at
|
|
762
|
startup the file referenced by this variable. If you put the following code at
|
|
762
|
startup the file referenced by this variable. If you put the following code at
|
|
763
|
the end of that file, then IPython will be your working environment anytime you
|
|
763
|
the end of that file, then IPython will be your working environment anytime you
|
|
764
|
start Python::
|
|
764
|
start Python::
|
|
765
|
|
|
765
|
|
|
766
|
from IPython.frontend.terminal.ipapp import launch_new_instance
|
|
766
|
from IPython.frontend.terminal.ipapp import launch_new_instance
|
|
767
|
launch_new_instance()
|
|
767
|
launch_new_instance()
|
|
768
|
raise SystemExit
|
|
768
|
raise SystemExit
|
|
769
|
|
|
769
|
|
|
770
|
The ``raise SystemExit`` is needed to exit Python when
|
|
770
|
The ``raise SystemExit`` is needed to exit Python when
|
|
771
|
it finishes, otherwise you'll be back at the normal Python '>>>'
|
|
771
|
it finishes, otherwise you'll be back at the normal Python '>>>'
|
|
772
|
prompt.
|
|
772
|
prompt.
|
|
773
|
|
|
773
|
|
|
774
|
This is probably useful to developers who manage multiple Python
|
|
774
|
This is probably useful to developers who manage multiple Python
|
|
775
|
versions and don't want to have correspondingly multiple IPython
|
|
775
|
versions and don't want to have correspondingly multiple IPython
|
|
776
|
versions. Note that in this mode, there is no way to pass IPython any
|
|
776
|
versions. Note that in this mode, there is no way to pass IPython any
|
|
777
|
command-line options, as those are trapped first by Python itself.
|
|
777
|
command-line options, as those are trapped first by Python itself.
|
|
778
|
|
|
778
|
|
|
779
|
.. _Embedding:
|
|
779
|
.. _Embedding:
|
|
780
|
|
|
780
|
|
|
781
|
Embedding IPython
|
|
781
|
Embedding IPython
|
|
782
|
=================
|
|
782
|
=================
|
|
783
|
|
|
783
|
|
|
784
|
It is possible to start an IPython instance inside your own Python
|
|
784
|
It is possible to start an IPython instance inside your own Python
|
|
785
|
programs. This allows you to evaluate dynamically the state of your
|
|
785
|
programs. This allows you to evaluate dynamically the state of your
|
|
786
|
code, operate with your variables, analyze them, etc. Note however that
|
|
786
|
code, operate with your variables, analyze them, etc. Note however that
|
|
787
|
any changes you make to values while in the shell do not propagate back
|
|
787
|
any changes you make to values while in the shell do not propagate back
|
|
788
|
to the running code, so it is safe to modify your values because you
|
|
788
|
to the running code, so it is safe to modify your values because you
|
|
789
|
won't break your code in bizarre ways by doing so.
|
|
789
|
won't break your code in bizarre ways by doing so.
|
|
790
|
|
|
790
|
|
|
791
|
.. note::
|
|
791
|
.. note::
|
|
792
|
|
|
792
|
|
|
793
|
At present, trying to embed IPython from inside IPython causes problems. Run
|
|
793
|
At present, trying to embed IPython from inside IPython causes problems. Run
|
|
794
|
the code samples below outside IPython.
|
|
794
|
the code samples below outside IPython.
|
|
795
|
|
|
795
|
|
|
796
|
This feature allows you to easily have a fully functional python
|
|
796
|
This feature allows you to easily have a fully functional python
|
|
797
|
environment for doing object introspection anywhere in your code with a
|
|
797
|
environment for doing object introspection anywhere in your code with a
|
|
798
|
simple function call. In some cases a simple print statement is enough,
|
|
798
|
simple function call. In some cases a simple print statement is enough,
|
|
799
|
but if you need to do more detailed analysis of a code fragment this
|
|
799
|
but if you need to do more detailed analysis of a code fragment this
|
|
800
|
feature can be very valuable.
|
|
800
|
feature can be very valuable.
|
|
801
|
|
|
801
|
|
|
802
|
It can also be useful in scientific computing situations where it is
|
|
802
|
It can also be useful in scientific computing situations where it is
|
|
803
|
common to need to do some automatic, computationally intensive part and
|
|
803
|
common to need to do some automatic, computationally intensive part and
|
|
804
|
then stop to look at data, plots, etc.
|
|
804
|
then stop to look at data, plots, etc.
|
|
805
|
Opening an IPython instance will give you full access to your data and
|
|
805
|
Opening an IPython instance will give you full access to your data and
|
|
806
|
functions, and you can resume program execution once you are done with
|
|
806
|
functions, and you can resume program execution once you are done with
|
|
807
|
the interactive part (perhaps to stop again later, as many times as
|
|
807
|
the interactive part (perhaps to stop again later, as many times as
|
|
808
|
needed).
|
|
808
|
needed).
|
|
809
|
|
|
809
|
|
|
810
|
The following code snippet is the bare minimum you need to include in
|
|
810
|
The following code snippet is the bare minimum you need to include in
|
|
811
|
your Python programs for this to work (detailed examples follow later)::
|
|
811
|
your Python programs for this to work (detailed examples follow later)::
|
|
812
|
|
|
812
|
|
|
813
|
from IPython import embed
|
|
813
|
from IPython import embed
|
|
814
|
|
|
814
|
|
|
815
|
embed() # this call anywhere in your program will start IPython
|
|
815
|
embed() # this call anywhere in your program will start IPython
|
|
816
|
|
|
816
|
|
|
817
|
.. note::
|
|
817
|
.. note::
|
|
818
|
|
|
818
|
|
|
819
|
As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
|
|
819
|
As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
|
|
820
|
etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
|
|
820
|
etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
|
|
821
|
It should function just the same as regular embed, but you connect
|
|
821
|
It should function just the same as regular embed, but you connect
|
|
822
|
an external frontend rather than IPython starting up in the local
|
|
822
|
an external frontend rather than IPython starting up in the local
|
|
823
|
terminal.
|
|
823
|
terminal.
|
|
824
|
|
|
824
|
|
|
825
|
You can run embedded instances even in code which is itself being run at
|
|
825
|
You can run embedded instances even in code which is itself being run at
|
|
826
|
the IPython interactive prompt with '%run <filename>'. Since it's easy
|
|
826
|
the IPython interactive prompt with '%run <filename>'. Since it's easy
|
|
827
|
to get lost as to where you are (in your top-level IPython or in your
|
|
827
|
to get lost as to where you are (in your top-level IPython or in your
|
|
828
|
embedded one), it's a good idea in such cases to set the in/out prompts
|
|
828
|
embedded one), it's a good idea in such cases to set the in/out prompts
|
|
829
|
to something different for the embedded instances. The code examples
|
|
829
|
to something different for the embedded instances. The code examples
|
|
830
|
below illustrate this.
|
|
830
|
below illustrate this.
|
|
831
|
|
|
831
|
|
|
832
|
You can also have multiple IPython instances in your program and open
|
|
832
|
You can also have multiple IPython instances in your program and open
|
|
833
|
them separately, for example with different options for data
|
|
833
|
them separately, for example with different options for data
|
|
834
|
presentation. If you close and open the same instance multiple times,
|
|
834
|
presentation. If you close and open the same instance multiple times,
|
|
835
|
its prompt counters simply continue from each execution to the next.
|
|
835
|
its prompt counters simply continue from each execution to the next.
|
|
836
|
|
|
836
|
|
|
837
|
Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
|
|
837
|
Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
|
|
838
|
module for more details on the use of this system.
|
|
838
|
module for more details on the use of this system.
|
|
839
|
|
|
839
|
|
|
840
|
The following sample file illustrating how to use the embedding
|
|
840
|
The following sample file illustrating how to use the embedding
|
|
841
|
functionality is provided in the examples directory as example-embed.py.
|
|
841
|
functionality is provided in the examples directory as example-embed.py.
|
|
842
|
It should be fairly self-explanatory:
|
|
842
|
It should be fairly self-explanatory:
|
|
843
|
|
|
843
|
|
|
844
|
.. literalinclude:: ../../examples/core/example-embed.py
|
|
844
|
.. literalinclude:: ../../../examples/core/example-embed.py
|
|
845
|
:language: python
|
|
845
|
:language: python
|
|
846
|
|
|
846
|
|
|
847
|
Once you understand how the system functions, you can use the following
|
|
847
|
Once you understand how the system functions, you can use the following
|
|
848
|
code fragments in your programs which are ready for cut and paste:
|
|
848
|
code fragments in your programs which are ready for cut and paste:
|
|
849
|
|
|
849
|
|
|
850
|
.. literalinclude:: ../../examples/core/example-embed-short.py
|
|
850
|
.. literalinclude:: ../../../examples/core/example-embed-short.py
|
|
851
|
:language: python
|
|
851
|
:language: python
|
|
852
|
|
|
852
|
|
|
853
|
Using the Python debugger (pdb)
|
|
853
|
Using the Python debugger (pdb)
|
|
854
|
===============================
|
|
854
|
===============================
|
|
855
|
|
|
855
|
|
|
856
|
Running entire programs via pdb
|
|
856
|
Running entire programs via pdb
|
|
857
|
-------------------------------
|
|
857
|
-------------------------------
|
|
858
|
|
|
858
|
|
|
859
|
pdb, the Python debugger, is a powerful interactive debugger which
|
|
859
|
pdb, the Python debugger, is a powerful interactive debugger which
|
|
860
|
allows you to step through code, set breakpoints, watch variables,
|
|
860
|
allows you to step through code, set breakpoints, watch variables,
|
|
861
|
etc. IPython makes it very easy to start any script under the control
|
|
861
|
etc. IPython makes it very easy to start any script under the control
|
|
862
|
of pdb, regardless of whether you have wrapped it into a 'main()'
|
|
862
|
of pdb, regardless of whether you have wrapped it into a 'main()'
|
|
863
|
function or not. For this, simply type '%run -d myscript' at an
|
|
863
|
function or not. For this, simply type '%run -d myscript' at an
|
|
864
|
IPython prompt. See the %run command's documentation (via '%run?' or
|
|
864
|
IPython prompt. See the %run command's documentation (via '%run?' or
|
|
865
|
in Sec. magic_ for more details, including how to control where pdb
|
|
865
|
in Sec. magic_ for more details, including how to control where pdb
|
|
866
|
will stop execution first.
|
|
866
|
will stop execution first.
|
|
867
|
|
|
867
|
|
|
868
|
For more information on the use of the pdb debugger, read the included
|
|
868
|
For more information on the use of the pdb debugger, read the included
|
|
869
|
pdb.doc file (part of the standard Python distribution). On a stock
|
|
869
|
pdb.doc file (part of the standard Python distribution). On a stock
|
|
870
|
Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
|
|
870
|
Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
|
|
871
|
easiest way to read it is by using the help() function of the pdb module
|
|
871
|
easiest way to read it is by using the help() function of the pdb module
|
|
872
|
as follows (in an IPython prompt)::
|
|
872
|
as follows (in an IPython prompt)::
|
|
873
|
|
|
873
|
|
|
874
|
In [1]: import pdb
|
|
874
|
In [1]: import pdb
|
|
875
|
In [2]: pdb.help()
|
|
875
|
In [2]: pdb.help()
|
|
876
|
|
|
876
|
|
|
877
|
This will load the pdb.doc document in a file viewer for you automatically.
|
|
877
|
This will load the pdb.doc document in a file viewer for you automatically.
|
|
878
|
|
|
878
|
|
|
879
|
|
|
879
|
|
|
880
|
Automatic invocation of pdb on exceptions
|
|
880
|
Automatic invocation of pdb on exceptions
|
|
881
|
-----------------------------------------
|
|
881
|
-----------------------------------------
|
|
882
|
|
|
882
|
|
|
883
|
IPython, if started with the ``--pdb`` option (or if the option is set in
|
|
883
|
IPython, if started with the ``--pdb`` option (or if the option is set in
|
|
884
|
your config file) can call the Python pdb debugger every time your code
|
|
884
|
your config file) can call the Python pdb debugger every time your code
|
|
885
|
triggers an uncaught exception. This feature
|
|
885
|
triggers an uncaught exception. This feature
|
|
886
|
can also be toggled at any time with the %pdb magic command. This can be
|
|
886
|
can also be toggled at any time with the %pdb magic command. This can be
|
|
887
|
extremely useful in order to find the origin of subtle bugs, because pdb
|
|
887
|
extremely useful in order to find the origin of subtle bugs, because pdb
|
|
888
|
opens up at the point in your code which triggered the exception, and
|
|
888
|
opens up at the point in your code which triggered the exception, and
|
|
889
|
while your program is at this point 'dead', all the data is still
|
|
889
|
while your program is at this point 'dead', all the data is still
|
|
890
|
available and you can walk up and down the stack frame and understand
|
|
890
|
available and you can walk up and down the stack frame and understand
|
|
891
|
the origin of the problem.
|
|
891
|
the origin of the problem.
|
|
892
|
|
|
892
|
|
|
893
|
Furthermore, you can use these debugging facilities both with the
|
|
893
|
Furthermore, you can use these debugging facilities both with the
|
|
894
|
embedded IPython mode and without IPython at all. For an embedded shell
|
|
894
|
embedded IPython mode and without IPython at all. For an embedded shell
|
|
895
|
(see sec. Embedding_), simply call the constructor with
|
|
895
|
(see sec. Embedding_), simply call the constructor with
|
|
896
|
``--pdb`` in the argument string and pdb will automatically be called if an
|
|
896
|
``--pdb`` in the argument string and pdb will automatically be called if an
|
|
897
|
uncaught exception is triggered by your code.
|
|
897
|
uncaught exception is triggered by your code.
|
|
898
|
|
|
898
|
|
|
899
|
For stand-alone use of the feature in your programs which do not use
|
|
899
|
For stand-alone use of the feature in your programs which do not use
|
|
900
|
IPython at all, put the following lines toward the top of your 'main'
|
|
900
|
IPython at all, put the following lines toward the top of your 'main'
|
|
901
|
routine::
|
|
901
|
routine::
|
|
902
|
|
|
902
|
|
|
903
|
import sys
|
|
903
|
import sys
|
|
904
|
from IPython.core import ultratb
|
|
904
|
from IPython.core import ultratb
|
|
905
|
sys.excepthook = ultratb.FormattedTB(mode='Verbose',
|
|
905
|
sys.excepthook = ultratb.FormattedTB(mode='Verbose',
|
|
906
|
color_scheme='Linux', call_pdb=1)
|
|
906
|
color_scheme='Linux', call_pdb=1)
|
|
907
|
|
|
907
|
|
|
908
|
The mode keyword can be either 'Verbose' or 'Plain', giving either very
|
|
908
|
The mode keyword can be either 'Verbose' or 'Plain', giving either very
|
|
909
|
detailed or normal tracebacks respectively. The color_scheme keyword can
|
|
909
|
detailed or normal tracebacks respectively. The color_scheme keyword can
|
|
910
|
be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
|
|
910
|
be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
|
|
911
|
options which can be set in IPython with ``--colors`` and ``--xmode``.
|
|
911
|
options which can be set in IPython with ``--colors`` and ``--xmode``.
|
|
912
|
|
|
912
|
|
|
913
|
This will give any of your programs detailed, colored tracebacks with
|
|
913
|
This will give any of your programs detailed, colored tracebacks with
|
|
914
|
automatic invocation of pdb.
|
|
914
|
automatic invocation of pdb.
|
|
915
|
|
|
915
|
|
|
916
|
|
|
916
|
|
|
917
|
Extensions for syntax processing
|
|
917
|
Extensions for syntax processing
|
|
918
|
================================
|
|
918
|
================================
|
|
919
|
|
|
919
|
|
|
920
|
This isn't for the faint of heart, because the potential for breaking
|
|
920
|
This isn't for the faint of heart, because the potential for breaking
|
|
921
|
things is quite high. But it can be a very powerful and useful feature.
|
|
921
|
things is quite high. But it can be a very powerful and useful feature.
|
|
922
|
In a nutshell, you can redefine the way IPython processes the user input
|
|
922
|
In a nutshell, you can redefine the way IPython processes the user input
|
|
923
|
line to accept new, special extensions to the syntax without needing to
|
|
923
|
line to accept new, special extensions to the syntax without needing to
|
|
924
|
change any of IPython's own code.
|
|
924
|
change any of IPython's own code.
|
|
925
|
|
|
925
|
|
|
926
|
In the IPython/extensions directory you will find some examples
|
|
926
|
In the IPython/extensions directory you will find some examples
|
|
927
|
supplied, which we will briefly describe now. These can be used 'as is'
|
|
927
|
supplied, which we will briefly describe now. These can be used 'as is'
|
|
928
|
(and both provide very useful functionality), or you can use them as a
|
|
928
|
(and both provide very useful functionality), or you can use them as a
|
|
929
|
starting point for writing your own extensions.
|
|
929
|
starting point for writing your own extensions.
|
|
930
|
|
|
930
|
|
|
931
|
.. _pasting_with_prompts:
|
|
931
|
.. _pasting_with_prompts:
|
|
932
|
|
|
932
|
|
|
933
|
Pasting of code starting with Python or IPython prompts
|
|
933
|
Pasting of code starting with Python or IPython prompts
|
|
934
|
-------------------------------------------------------
|
|
934
|
-------------------------------------------------------
|
|
935
|
|
|
935
|
|
|
936
|
IPython is smart enough to filter out input prompts, be they plain Python ones
|
|
936
|
IPython is smart enough to filter out input prompts, be they plain Python ones
|
|
937
|
(``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
|
|
937
|
(``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
|
|
938
|
therefore copy and paste from existing interactive sessions without worry.
|
|
938
|
therefore copy and paste from existing interactive sessions without worry.
|
|
939
|
|
|
939
|
|
|
940
|
The following is a 'screenshot' of how things work, copying an example from the
|
|
940
|
The following is a 'screenshot' of how things work, copying an example from the
|
|
941
|
standard Python tutorial::
|
|
941
|
standard Python tutorial::
|
|
942
|
|
|
942
|
|
|
943
|
In [1]: >>> # Fibonacci series:
|
|
943
|
In [1]: >>> # Fibonacci series:
|
|
944
|
|
|
944
|
|
|
945
|
In [2]: ... # the sum of two elements defines the next
|
|
945
|
In [2]: ... # the sum of two elements defines the next
|
|
946
|
|
|
946
|
|
|
947
|
In [3]: ... a, b = 0, 1
|
|
947
|
In [3]: ... a, b = 0, 1
|
|
948
|
|
|
948
|
|
|
949
|
In [4]: >>> while b < 10:
|
|
949
|
In [4]: >>> while b < 10:
|
|
950
|
...: ... print b
|
|
950
|
...: ... print b
|
|
951
|
...: ... a, b = b, a+b
|
|
951
|
...: ... a, b = b, a+b
|
|
952
|
...:
|
|
952
|
...:
|
|
953
|
1
|
|
953
|
1
|
|
954
|
1
|
|
954
|
1
|
|
955
|
2
|
|
955
|
2
|
|
956
|
3
|
|
956
|
3
|
|
957
|
5
|
|
957
|
5
|
|
958
|
8
|
|
958
|
8
|
|
959
|
|
|
959
|
|
|
960
|
And pasting from IPython sessions works equally well::
|
|
960
|
And pasting from IPython sessions works equally well::
|
|
961
|
|
|
961
|
|
|
962
|
In [1]: In [5]: def f(x):
|
|
962
|
In [1]: In [5]: def f(x):
|
|
963
|
...: ...: "A simple function"
|
|
963
|
...: ...: "A simple function"
|
|
964
|
...: ...: return x**2
|
|
964
|
...: ...: return x**2
|
|
965
|
...: ...:
|
|
965
|
...: ...:
|
|
966
|
|
|
966
|
|
|
967
|
In [2]: f(3)
|
|
967
|
In [2]: f(3)
|
|
968
|
Out[2]: 9
|
|
968
|
Out[2]: 9
|
|
969
|
|
|
969
|
|
|
970
|
.. _gui_support:
|
|
970
|
.. _gui_support:
|
|
971
|
|
|
971
|
|
|
972
|
GUI event loop support
|
|
972
|
GUI event loop support
|
|
973
|
======================
|
|
973
|
======================
|
|
974
|
|
|
974
|
|
|
975
|
.. versionadded:: 0.11
|
|
975
|
.. versionadded:: 0.11
|
|
976
|
The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
|
|
976
|
The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
|
|
977
|
|
|
977
|
|
|
978
|
IPython has excellent support for working interactively with Graphical User
|
|
978
|
IPython has excellent support for working interactively with Graphical User
|
|
979
|
Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
|
|
979
|
Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
|
|
980
|
implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
|
|
980
|
implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
|
|
981
|
is extremely robust compared to our previous thread-based version. The
|
|
981
|
is extremely robust compared to our previous thread-based version. The
|
|
982
|
advantages of this are:
|
|
982
|
advantages of this are:
|
|
983
|
|
|
983
|
|
|
984
|
* GUIs can be enabled and disabled dynamically at runtime.
|
|
984
|
* GUIs can be enabled and disabled dynamically at runtime.
|
|
985
|
* The active GUI can be switched dynamically at runtime.
|
|
985
|
* The active GUI can be switched dynamically at runtime.
|
|
986
|
* In some cases, multiple GUIs can run simultaneously with no problems.
|
|
986
|
* In some cases, multiple GUIs can run simultaneously with no problems.
|
|
987
|
* There is a developer API in :mod:`IPython.lib.inputhook` for customizing
|
|
987
|
* There is a developer API in :mod:`IPython.lib.inputhook` for customizing
|
|
988
|
all of these things.
|
|
988
|
all of these things.
|
|
989
|
|
|
989
|
|
|
990
|
For users, enabling GUI event loop integration is simple. You simple use the
|
|
990
|
For users, enabling GUI event loop integration is simple. You simple use the
|
|
991
|
``%gui`` magic as follows::
|
|
991
|
``%gui`` magic as follows::
|
|
992
|
|
|
992
|
|
|
993
|
%gui [GUINAME]
|
|
993
|
%gui [GUINAME]
|
|
994
|
|
|
994
|
|
|
995
|
With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
|
|
995
|
With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
|
|
996
|
arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
|
|
996
|
arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
|
|
997
|
|
|
997
|
|
|
998
|
Thus, to use wxPython interactively and create a running :class:`wx.App`
|
|
998
|
Thus, to use wxPython interactively and create a running :class:`wx.App`
|
|
999
|
object, do::
|
|
999
|
object, do::
|
|
1000
|
|
|
1000
|
|
|
1001
|
%gui wx
|
|
1001
|
%gui wx
|
|
1002
|
|
|
1002
|
|
|
1003
|
For information on IPython's Matplotlib integration (and the ``pylab`` mode)
|
|
1003
|
For information on IPython's Matplotlib integration (and the ``pylab`` mode)
|
|
1004
|
see :ref:`this section <matplotlib_support>`.
|
|
1004
|
see :ref:`this section <matplotlib_support>`.
|
|
1005
|
|
|
1005
|
|
|
1006
|
For developers that want to use IPython's GUI event loop integration in the
|
|
1006
|
For developers that want to use IPython's GUI event loop integration in the
|
|
1007
|
form of a library, these capabilities are exposed in library form in the
|
|
1007
|
form of a library, these capabilities are exposed in library form in the
|
|
1008
|
:mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
|
|
1008
|
:mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
|
|
1009
|
Interested developers should see the module docstrings for more information,
|
|
1009
|
Interested developers should see the module docstrings for more information,
|
|
1010
|
but there are a few points that should be mentioned here.
|
|
1010
|
but there are a few points that should be mentioned here.
|
|
1011
|
|
|
1011
|
|
|
1012
|
First, the ``PyOSInputHook`` approach only works in command line settings
|
|
1012
|
First, the ``PyOSInputHook`` approach only works in command line settings
|
|
1013
|
where readline is activated. The integration with various eventloops
|
|
1013
|
where readline is activated. The integration with various eventloops
|
|
1014
|
is handled somewhat differently (and more simply) when using the standalone
|
|
1014
|
is handled somewhat differently (and more simply) when using the standalone
|
|
1015
|
kernel, as in the qtconsole and notebook.
|
|
1015
|
kernel, as in the qtconsole and notebook.
|
|
1016
|
|
|
1016
|
|
|
1017
|
Second, when using the ``PyOSInputHook`` approach, a GUI application should
|
|
1017
|
Second, when using the ``PyOSInputHook`` approach, a GUI application should
|
|
1018
|
*not* start its event loop. Instead all of this is handled by the
|
|
1018
|
*not* start its event loop. Instead all of this is handled by the
|
|
1019
|
``PyOSInputHook``. This means that applications that are meant to be used both
|
|
1019
|
``PyOSInputHook``. This means that applications that are meant to be used both
|
|
1020
|
in IPython and as standalone apps need to have special code to detects how the
|
|
1020
|
in IPython and as standalone apps need to have special code to detects how the
|
|
1021
|
application is being run. We highly recommend using IPython's support for this.
|
|
1021
|
application is being run. We highly recommend using IPython's support for this.
|
|
1022
|
Since the details vary slightly between toolkits, we point you to the various
|
|
1022
|
Since the details vary slightly between toolkits, we point you to the various
|
|
1023
|
examples in our source directory :file:`docs/examples/lib` that demonstrate
|
|
1023
|
examples in our source directory :file:`docs/examples/lib` that demonstrate
|
|
1024
|
these capabilities.
|
|
1024
|
these capabilities.
|
|
1025
|
|
|
1025
|
|
|
1026
|
Third, unlike previous versions of IPython, we no longer "hijack" (replace
|
|
1026
|
Third, unlike previous versions of IPython, we no longer "hijack" (replace
|
|
1027
|
them with no-ops) the event loops. This is done to allow applications that
|
|
1027
|
them with no-ops) the event loops. This is done to allow applications that
|
|
1028
|
actually need to run the real event loops to do so. This is often needed to
|
|
1028
|
actually need to run the real event loops to do so. This is often needed to
|
|
1029
|
process pending events at critical points.
|
|
1029
|
process pending events at critical points.
|
|
1030
|
|
|
1030
|
|
|
1031
|
Finally, we also have a number of examples in our source directory
|
|
1031
|
Finally, we also have a number of examples in our source directory
|
|
1032
|
:file:`docs/examples/lib` that demonstrate these capabilities.
|
|
1032
|
:file:`docs/examples/lib` that demonstrate these capabilities.
|
|
1033
|
|
|
1033
|
|
|
1034
|
PyQt and PySide
|
|
1034
|
PyQt and PySide
|
|
1035
|
---------------
|
|
1035
|
---------------
|
|
1036
|
|
|
1036
|
|
|
1037
|
.. attempt at explanation of the complete mess that is Qt support
|
|
1037
|
.. attempt at explanation of the complete mess that is Qt support
|
|
1038
|
|
|
1038
|
|
|
1039
|
When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
|
|
1039
|
When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
|
|
1040
|
PyQt4 or PySide. There are three options for configuration here, because
|
|
1040
|
PyQt4 or PySide. There are three options for configuration here, because
|
|
1041
|
PyQt4 has two APIs for QString and QVariant - v1, which is the default on
|
|
1041
|
PyQt4 has two APIs for QString and QVariant - v1, which is the default on
|
|
1042
|
Python 2, and the more natural v2, which is the only API supported by PySide.
|
|
1042
|
Python 2, and the more natural v2, which is the only API supported by PySide.
|
|
1043
|
v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
|
|
1043
|
v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
|
|
1044
|
uses v2, but you can still use any interface in your code, since the
|
|
1044
|
uses v2, but you can still use any interface in your code, since the
|
|
1045
|
Qt frontend is in a different process.
|
|
1045
|
Qt frontend is in a different process.
|
|
1046
|
|
|
1046
|
|
|
1047
|
The default will be to import PyQt4 without configuration of the APIs, thus
|
|
1047
|
The default will be to import PyQt4 without configuration of the APIs, thus
|
|
1048
|
matching what most applications would expect. It will fall back of PySide if
|
|
1048
|
matching what most applications would expect. It will fall back of PySide if
|
|
1049
|
PyQt4 is unavailable.
|
|
1049
|
PyQt4 is unavailable.
|
|
1050
|
|
|
1050
|
|
|
1051
|
If specified, IPython will respect the environment variable ``QT_API`` used
|
|
1051
|
If specified, IPython will respect the environment variable ``QT_API`` used
|
|
1052
|
by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
|
|
1052
|
by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
|
|
1053
|
PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
|
|
1053
|
PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
|
|
1054
|
and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
|
|
1054
|
and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
|
|
1055
|
QString and QVariant, so ETS codes like MayaVi will also work with IPython.
|
|
1055
|
QString and QVariant, so ETS codes like MayaVi will also work with IPython.
|
|
1056
|
|
|
1056
|
|
|
1057
|
If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
|
|
1057
|
If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
|
|
1058
|
will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
|
|
1058
|
will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
|
|
1059
|
the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
|
|
1059
|
the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
|
|
1060
|
IPython will always use PyQt4 without setting the v2 APIs, since neither v2
|
|
1060
|
IPython will always use PyQt4 without setting the v2 APIs, since neither v2
|
|
1061
|
PyQt nor PySide work.
|
|
1061
|
PyQt nor PySide work.
|
|
1062
|
|
|
1062
|
|
|
1063
|
.. warning::
|
|
1063
|
.. warning::
|
|
1064
|
|
|
1064
|
|
|
1065
|
Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
|
|
1065
|
Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
|
|
1066
|
to work with IPython's qt integration, because otherwise PyQt4 will be
|
|
1066
|
to work with IPython's qt integration, because otherwise PyQt4 will be
|
|
1067
|
loaded in an incompatible mode.
|
|
1067
|
loaded in an incompatible mode.
|
|
1068
|
|
|
1068
|
|
|
1069
|
It also means that you must *not* have ``QT_API`` set if you want to
|
|
1069
|
It also means that you must *not* have ``QT_API`` set if you want to
|
|
1070
|
use ``--gui=qt`` with code that requires PyQt4 API v1.
|
|
1070
|
use ``--gui=qt`` with code that requires PyQt4 API v1.
|
|
1071
|
|
|
1071
|
|
|
1072
|
|
|
1072
|
|
|
1073
|
.. _matplotlib_support:
|
|
1073
|
.. _matplotlib_support:
|
|
1074
|
|
|
1074
|
|
|
1075
|
Plotting with matplotlib
|
|
1075
|
Plotting with matplotlib
|
|
1076
|
========================
|
|
1076
|
========================
|
|
1077
|
|
|
1077
|
|
|
1078
|
`Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
|
|
1078
|
`Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
|
|
1079
|
can produce plots on screen using a variety of GUI toolkits, including Tk,
|
|
1079
|
can produce plots on screen using a variety of GUI toolkits, including Tk,
|
|
1080
|
PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
|
|
1080
|
PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
|
|
1081
|
scientific computing, all with a syntax compatible with that of the popular
|
|
1081
|
scientific computing, all with a syntax compatible with that of the popular
|
|
1082
|
Matlab program.
|
|
1082
|
Matlab program.
|
|
1083
|
|
|
1083
|
|
|
1084
|
To start IPython with matplotlib support, use the ``--pylab`` switch. If no
|
|
1084
|
To start IPython with matplotlib support, use the ``--pylab`` switch. If no
|
|
1085
|
arguments are given, IPython will automatically detect your choice of
|
|
1085
|
arguments are given, IPython will automatically detect your choice of
|
|
1086
|
matplotlib backend. You can also request a specific backend with ``--pylab
|
|
1086
|
matplotlib backend. You can also request a specific backend with ``--pylab
|
|
1087
|
backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', 'osx'.
|
|
1087
|
backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', 'osx'.
|
|
1088
|
In the web notebook and Qt console, 'inline' is also a valid backend value,
|
|
1088
|
In the web notebook and Qt console, 'inline' is also a valid backend value,
|
|
1089
|
which produces static figures inlined inside the application window instead of
|
|
1089
|
which produces static figures inlined inside the application window instead of
|
|
1090
|
matplotlib's interactive figures that live in separate windows.
|
|
1090
|
matplotlib's interactive figures that live in separate windows.
|
|
1091
|
|
|
1091
|
|
|
1092
|
.. _Matplotlib: http://matplotlib.sourceforge.net
|
|
1092
|
.. _Matplotlib: http://matplotlib.sourceforge.net
|
|
1093
|
|
|
1093
|
|
|
1094
|
.. _interactive_demos:
|
|
1094
|
.. _interactive_demos:
|
|
1095
|
|
|
1095
|
|
|
1096
|
Interactive demos with IPython
|
|
1096
|
Interactive demos with IPython
|
|
1097
|
==============================
|
|
1097
|
==============================
|
|
1098
|
|
|
1098
|
|
|
1099
|
IPython ships with a basic system for running scripts interactively in
|
|
1099
|
IPython ships with a basic system for running scripts interactively in
|
|
1100
|
sections, useful when presenting code to audiences. A few tags embedded
|
|
1100
|
sections, useful when presenting code to audiences. A few tags embedded
|
|
1101
|
in comments (so that the script remains valid Python code) divide a file
|
|
1101
|
in comments (so that the script remains valid Python code) divide a file
|
|
1102
|
into separate blocks, and the demo can be run one block at a time, with
|
|
1102
|
into separate blocks, and the demo can be run one block at a time, with
|
|
1103
|
IPython printing (with syntax highlighting) the block before executing
|
|
1103
|
IPython printing (with syntax highlighting) the block before executing
|
|
1104
|
it, and returning to the interactive prompt after each block. The
|
|
1104
|
it, and returning to the interactive prompt after each block. The
|
|
1105
|
interactive namespace is updated after each block is run with the
|
|
1105
|
interactive namespace is updated after each block is run with the
|
|
1106
|
contents of the demo's namespace.
|
|
1106
|
contents of the demo's namespace.
|
|
1107
|
|
|
1107
|
|
|
1108
|
This allows you to show a piece of code, run it and then execute
|
|
1108
|
This allows you to show a piece of code, run it and then execute
|
|
1109
|
interactively commands based on the variables just created. Once you
|
|
1109
|
interactively commands based on the variables just created. Once you
|
|
1110
|
want to continue, you simply execute the next block of the demo. The
|
|
1110
|
want to continue, you simply execute the next block of the demo. The
|
|
1111
|
following listing shows the markup necessary for dividing a script into
|
|
1111
|
following listing shows the markup necessary for dividing a script into
|
|
1112
|
sections for execution as a demo:
|
|
1112
|
sections for execution as a demo:
|
|
1113
|
|
|
1113
|
|
|
1114
|
.. literalinclude:: ../../examples/lib/example-demo.py
|
|
1114
|
.. literalinclude:: ../../../examples/lib/example-demo.py
|
|
1115
|
:language: python
|
|
1115
|
:language: python
|
|
1116
|
|
|
1116
|
|
|
1117
|
In order to run a file as a demo, you must first make a Demo object out
|
|
1117
|
In order to run a file as a demo, you must first make a Demo object out
|
|
1118
|
of it. If the file is named myscript.py, the following code will make a
|
|
1118
|
of it. If the file is named myscript.py, the following code will make a
|
|
1119
|
demo::
|
|
1119
|
demo::
|
|
1120
|
|
|
1120
|
|
|
1121
|
from IPython.lib.demo import Demo
|
|
1121
|
from IPython.lib.demo import Demo
|
|
1122
|
|
|
1122
|
|
|
1123
|
mydemo = Demo('myscript.py')
|
|
1123
|
mydemo = Demo('myscript.py')
|
|
1124
|
|
|
1124
|
|
|
1125
|
This creates the mydemo object, whose blocks you run one at a time by
|
|
1125
|
This creates the mydemo object, whose blocks you run one at a time by
|
|
1126
|
simply calling the object with no arguments. If you have autocall active
|
|
1126
|
simply calling the object with no arguments. If you have autocall active
|
|
1127
|
in IPython (the default), all you need to do is type::
|
|
1127
|
in IPython (the default), all you need to do is type::
|
|
1128
|
|
|
1128
|
|
|
1129
|
mydemo
|
|
1129
|
mydemo
|
|
1130
|
|
|
1130
|
|
|
1131
|
and IPython will call it, executing each block. Demo objects can be
|
|
1131
|
and IPython will call it, executing each block. Demo objects can be
|
|
1132
|
restarted, you can move forward or back skipping blocks, re-execute the
|
|
1132
|
restarted, you can move forward or back skipping blocks, re-execute the
|
|
1133
|
last block, etc. Simply use the Tab key on a demo object to see its
|
|
1133
|
last block, etc. Simply use the Tab key on a demo object to see its
|
|
1134
|
methods, and call '?' on them to see their docstrings for more usage
|
|
1134
|
methods, and call '?' on them to see their docstrings for more usage
|
|
1135
|
details. In addition, the demo module itself contains a comprehensive
|
|
1135
|
details. In addition, the demo module itself contains a comprehensive
|
|
1136
|
docstring, which you can access via::
|
|
1136
|
docstring, which you can access via::
|
|
1137
|
|
|
1137
|
|
|
1138
|
from IPython.lib import demo
|
|
1138
|
from IPython.lib import demo
|
|
1139
|
|
|
1139
|
|
|
1140
|
demo?
|
|
1140
|
demo?
|
|
1141
|
|
|
1141
|
|
|
1142
|
Limitations: It is important to note that these demos are limited to
|
|
1142
|
Limitations: It is important to note that these demos are limited to
|
|
1143
|
fairly simple uses. In particular, you cannot break up sections within
|
|
1143
|
fairly simple uses. In particular, you cannot break up sections within
|
|
1144
|
indented code (loops, if statements, function definitions, etc.)
|
|
1144
|
indented code (loops, if statements, function definitions, etc.)
|
|
1145
|
Supporting something like this would basically require tracking the
|
|
1145
|
Supporting something like this would basically require tracking the
|
|
1146
|
internal execution state of the Python interpreter, so only top-level
|
|
1146
|
internal execution state of the Python interpreter, so only top-level
|
|
1147
|
divisions are allowed. If you want to be able to open an IPython
|
|
1147
|
divisions are allowed. If you want to be able to open an IPython
|
|
1148
|
instance at an arbitrary point in a program, you can use IPython's
|
|
1148
|
instance at an arbitrary point in a program, you can use IPython's
|
|
1149
|
embedding facilities, see :func:`IPython.embed` for details.
|
|
1149
|
embedding facilities, see :func:`IPython.embed` for details.
|
|
1150
|
|
|
1150
|
|