##// END OF EJS Templates
Update docs about autocall and remove manual copy of cmd-line flags....
Fernando Perez -
Show More
@@ -1,529 +1,534 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Usage information for the main IPython applications.
2 """Usage information for the main IPython applications.
3 """
3 """
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2008-2011 The IPython Development Team
5 # Copyright (C) 2008-2011 The IPython Development Team
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 #
7 #
8 # Distributed under the terms of the BSD License. The full license is in
8 # Distributed under the terms of the BSD License. The full license is in
9 # the file COPYING, distributed as part of this software.
9 # the file COPYING, distributed as part of this software.
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11
11
12 import sys
12 import sys
13 from IPython.core import release
13 from IPython.core import release
14
14
15 cl_usage = """\
15 cl_usage = """\
16 =========
16 =========
17 IPython
17 IPython
18 =========
18 =========
19
19
20 Tools for Interactive Computing in Python
20 Tools for Interactive Computing in Python
21 =========================================
21 =========================================
22
22
23 A Python shell with automatic history (input and output), dynamic object
23 A Python shell with automatic history (input and output), dynamic object
24 introspection, easier configuration, command completion, access to the
24 introspection, easier configuration, command completion, access to the
25 system shell and more. IPython can also be embedded in running programs.
25 system shell and more. IPython can also be embedded in running programs.
26
26
27
27
28 Usage
28 Usage
29
29
30 ipython [subcommand] [options] [files]
30 ipython [subcommand] [options] [files]
31
31
32 If invoked with no options, it executes all the files listed in sequence
32 If invoked with no options, it executes all the files listed in sequence
33 and exits, use -i to enter interactive mode after running the files. Files
33 and exits, use -i to enter interactive mode after running the files. Files
34 ending in .py will be treated as normal Python, but files ending in .ipy
34 ending in .py will be treated as normal Python, but files ending in .ipy
35 can contain special IPython syntax (magic commands, shell expansions, etc.)
35 can contain special IPython syntax (magic commands, shell expansions, etc.)
36
36
37 Almost all configuration in IPython is available via the command-line. Do
37 Almost all configuration in IPython is available via the command-line. Do
38 `ipython --help-all` to see all available options. For persistent
38 `ipython --help-all` to see all available options. For persistent
39 configuration, look into your `ipython_config.py` configuration file for
39 configuration, look into your `ipython_config.py` configuration file for
40 details.
40 details.
41
41
42 This file is typically installed in the `IPYTHON_DIR` directory, and there
42 This file is typically installed in the `IPYTHON_DIR` directory, and there
43 is a separate configuration directory for each profile. The default profile
43 is a separate configuration directory for each profile. The default profile
44 directory will be located in $IPYTHON_DIR/profile_default. For Linux users,
44 directory will be located in $IPYTHON_DIR/profile_default. For Linux users,
45 IPYTHON_DIR defaults to `$HOME/.config/ipython`, and for other Unix systems
45 IPYTHON_DIR defaults to `$HOME/.config/ipython`, and for other Unix systems
46 to `$HOME/.ipython`. For Windows users, $HOME resolves to C:\\Documents
46 to `$HOME/.ipython`. For Windows users, $HOME resolves to C:\\Documents
47 and Settings\\YourUserName in most instances.
47 and Settings\\YourUserName in most instances.
48
48
49 To initialize a profile with the default configuration file, do::
49 To initialize a profile with the default configuration file, do::
50
50
51 $> ipython profile create
51 $> ipython profile create
52
52
53 and start editing `IPYTHON_DIR/profile_default/ipython_config.py`
53 and start editing `IPYTHON_DIR/profile_default/ipython_config.py`
54
54
55 In IPython's documentation, we will refer to this directory as
55 In IPython's documentation, we will refer to this directory as
56 `IPYTHON_DIR`, you can change its default location by creating an
56 `IPYTHON_DIR`, you can change its default location by creating an
57 environment variable with this name and setting it to the desired path.
57 environment variable with this name and setting it to the desired path.
58
58
59 For more information, see the manual available in HTML and PDF in your
59 For more information, see the manual available in HTML and PDF in your
60 installation, or online at http://ipython.org/documentation.html.
60 installation, or online at http://ipython.org/documentation.html.
61 """
61 """
62
62
63 interactive_usage = """
63 interactive_usage = """
64 IPython -- An enhanced Interactive Python
64 IPython -- An enhanced Interactive Python
65 =========================================
65 =========================================
66
66
67 IPython offers a combination of convenient shell features, special commands
67 IPython offers a combination of convenient shell features, special commands
68 and a history mechanism for both input (command history) and output (results
68 and a history mechanism for both input (command history) and output (results
69 caching, similar to Mathematica). It is intended to be a fully compatible
69 caching, similar to Mathematica). It is intended to be a fully compatible
70 replacement for the standard Python interpreter, while offering vastly
70 replacement for the standard Python interpreter, while offering vastly
71 improved functionality and flexibility.
71 improved functionality and flexibility.
72
72
73 At your system command line, type 'ipython -h' to see the command line
73 At your system command line, type 'ipython -h' to see the command line
74 options available. This document only describes interactive features.
74 options available. This document only describes interactive features.
75
75
76 MAIN FEATURES
76 MAIN FEATURES
77
77
78 * Access to the standard Python help. As of Python 2.1, a help system is
78 * Access to the standard Python help. As of Python 2.1, a help system is
79 available with access to object docstrings and the Python manuals. Simply
79 available with access to object docstrings and the Python manuals. Simply
80 type 'help' (no quotes) to access it.
80 type 'help' (no quotes) to access it.
81
81
82 * Magic commands: type %magic for information on the magic subsystem.
82 * Magic commands: type %magic for information on the magic subsystem.
83
83
84 * System command aliases, via the %alias command or the configuration file(s).
84 * System command aliases, via the %alias command or the configuration file(s).
85
85
86 * Dynamic object information:
86 * Dynamic object information:
87
87
88 Typing ?word or word? prints detailed information about an object. If
88 Typing ?word or word? prints detailed information about an object. If
89 certain strings in the object are too long (docstrings, code, etc.) they get
89 certain strings in the object are too long (docstrings, code, etc.) they get
90 snipped in the center for brevity.
90 snipped in the center for brevity.
91
91
92 Typing ??word or word?? gives access to the full information without
92 Typing ??word or word?? gives access to the full information without
93 snipping long strings. Long strings are sent to the screen through the less
93 snipping long strings. Long strings are sent to the screen through the less
94 pager if longer than the screen, printed otherwise.
94 pager if longer than the screen, printed otherwise.
95
95
96 The ?/?? system gives access to the full source code for any object (if
96 The ?/?? system gives access to the full source code for any object (if
97 available), shows function prototypes and other useful information.
97 available), shows function prototypes and other useful information.
98
98
99 If you just want to see an object's docstring, type '%pdoc object' (without
99 If you just want to see an object's docstring, type '%pdoc object' (without
100 quotes, and without % if you have automagic on).
100 quotes, and without % if you have automagic on).
101
101
102 Both %pdoc and ?/?? give you access to documentation even on things which are
102 Both %pdoc and ?/?? give you access to documentation even on things which are
103 not explicitely defined. Try for example typing {}.get? or after import os,
103 not explicitely defined. Try for example typing {}.get? or after import os,
104 type os.path.abspath??. The magic functions %pdef, %source and %file operate
104 type os.path.abspath??. The magic functions %pdef, %source and %file operate
105 similarly.
105 similarly.
106
106
107 * Completion in the local namespace, by typing TAB at the prompt.
107 * Completion in the local namespace, by typing TAB at the prompt.
108
108
109 At any time, hitting tab will complete any available python commands or
109 At any time, hitting tab will complete any available python commands or
110 variable names, and show you a list of the possible completions if there's
110 variable names, and show you a list of the possible completions if there's
111 no unambiguous one. It will also complete filenames in the current directory.
111 no unambiguous one. It will also complete filenames in the current directory.
112
112
113 This feature requires the readline and rlcomplete modules, so it won't work
113 This feature requires the readline and rlcomplete modules, so it won't work
114 if your Python lacks readline support (such as under Windows).
114 if your Python lacks readline support (such as under Windows).
115
115
116 * Search previous command history in two ways (also requires readline):
116 * Search previous command history in two ways (also requires readline):
117
117
118 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
118 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
119 search through only the history items that match what you've typed so
119 search through only the history items that match what you've typed so
120 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
120 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
121 normal arrow keys.
121 normal arrow keys.
122
122
123 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
123 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
124 your history for lines that match what you've typed so far, completing as
124 your history for lines that match what you've typed so far, completing as
125 much as it can.
125 much as it can.
126
126
127 - %hist: search history by index (this does *not* require readline).
127 - %hist: search history by index (this does *not* require readline).
128
128
129 * Persistent command history across sessions.
129 * Persistent command history across sessions.
130
130
131 * Logging of input with the ability to save and restore a working session.
131 * Logging of input with the ability to save and restore a working session.
132
132
133 * System escape with !. Typing !ls will run 'ls' in the current directory.
133 * System escape with !. Typing !ls will run 'ls' in the current directory.
134
134
135 * The reload command does a 'deep' reload of a module: changes made to the
135 * The reload command does a 'deep' reload of a module: changes made to the
136 module since you imported will actually be available without having to exit.
136 module since you imported will actually be available without having to exit.
137
137
138 * Verbose and colored exception traceback printouts. See the magic xmode and
138 * Verbose and colored exception traceback printouts. See the magic xmode and
139 xcolor functions for details (just type %magic).
139 xcolor functions for details (just type %magic).
140
140
141 * Input caching system:
141 * Input caching system:
142
142
143 IPython offers numbered prompts (In/Out) with input and output caching. All
143 IPython offers numbered prompts (In/Out) with input and output caching. All
144 input is saved and can be retrieved as variables (besides the usual arrow
144 input is saved and can be retrieved as variables (besides the usual arrow
145 key recall).
145 key recall).
146
146
147 The following GLOBAL variables always exist (so don't overwrite them!):
147 The following GLOBAL variables always exist (so don't overwrite them!):
148 _i: stores previous input.
148 _i: stores previous input.
149 _ii: next previous.
149 _ii: next previous.
150 _iii: next-next previous.
150 _iii: next-next previous.
151 _ih : a list of all input _ih[n] is the input from line n.
151 _ih : a list of all input _ih[n] is the input from line n.
152
152
153 Additionally, global variables named _i<n> are dynamically created (<n>
153 Additionally, global variables named _i<n> are dynamically created (<n>
154 being the prompt counter), such that _i<n> == _ih[<n>]
154 being the prompt counter), such that _i<n> == _ih[<n>]
155
155
156 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
156 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
157
157
158 You can create macros which contain multiple input lines from this history,
158 You can create macros which contain multiple input lines from this history,
159 for later re-execution, with the %macro function.
159 for later re-execution, with the %macro function.
160
160
161 The history function %hist allows you to see any part of your input history
161 The history function %hist allows you to see any part of your input history
162 by printing a range of the _i variables. Note that inputs which contain
162 by printing a range of the _i variables. Note that inputs which contain
163 magic functions (%) appear in the history with a prepended comment. This is
163 magic functions (%) appear in the history with a prepended comment. This is
164 because they aren't really valid Python code, so you can't exec them.
164 because they aren't really valid Python code, so you can't exec them.
165
165
166 * Output caching system:
166 * Output caching system:
167
167
168 For output that is returned from actions, a system similar to the input
168 For output that is returned from actions, a system similar to the input
169 cache exists but using _ instead of _i. Only actions that produce a result
169 cache exists but using _ instead of _i. Only actions that produce a result
170 (NOT assignments, for example) are cached. If you are familiar with
170 (NOT assignments, for example) are cached. If you are familiar with
171 Mathematica, IPython's _ variables behave exactly like Mathematica's %
171 Mathematica, IPython's _ variables behave exactly like Mathematica's %
172 variables.
172 variables.
173
173
174 The following GLOBAL variables always exist (so don't overwrite them!):
174 The following GLOBAL variables always exist (so don't overwrite them!):
175 _ (one underscore): previous output.
175 _ (one underscore): previous output.
176 __ (two underscores): next previous.
176 __ (two underscores): next previous.
177 ___ (three underscores): next-next previous.
177 ___ (three underscores): next-next previous.
178
178
179 Global variables named _<n> are dynamically created (<n> being the prompt
179 Global variables named _<n> are dynamically created (<n> being the prompt
180 counter), such that the result of output <n> is always available as _<n>.
180 counter), such that the result of output <n> is always available as _<n>.
181
181
182 Finally, a global dictionary named _oh exists with entries for all lines
182 Finally, a global dictionary named _oh exists with entries for all lines
183 which generated output.
183 which generated output.
184
184
185 * Directory history:
185 * Directory history:
186
186
187 Your history of visited directories is kept in the global list _dh, and the
187 Your history of visited directories is kept in the global list _dh, and the
188 magic %cd command can be used to go to any entry in that list.
188 magic %cd command can be used to go to any entry in that list.
189
189
190 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
190 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
191
191
192 1. Auto-parentheses
192 1. Auto-parentheses
193 Callable objects (i.e. functions, methods, etc) can be invoked like
193 Callable objects (i.e. functions, methods, etc) can be invoked like
194 this (notice the commas between the arguments):
194 this (notice the commas between the arguments):
195 In [1]: callable_ob arg1, arg2, arg3
195 In [1]: callable_ob arg1, arg2, arg3
196 and the input will be translated to this:
196 and the input will be translated to this:
197 ------> callable_ob(arg1, arg2, arg3)
197 ------> callable_ob(arg1, arg2, arg3)
198 This feature is off by default (in rare cases it can produce
199 undesirable side-effects), but you can activate it at the command-line
200 by starting IPython with `--autocall 1`, set it permanently in your
201 configuration file, or turn on at runtime with `%autocall 1`.
202
198 You can force auto-parentheses by using '/' as the first character
203 You can force auto-parentheses by using '/' as the first character
199 of a line. For example:
204 of a line. For example:
200 In [1]: /globals # becomes 'globals()'
205 In [1]: /globals # becomes 'globals()'
201 Note that the '/' MUST be the first character on the line! This
206 Note that the '/' MUST be the first character on the line! This
202 won't work:
207 won't work:
203 In [2]: print /globals # syntax error
208 In [2]: print /globals # syntax error
204
209
205 In most cases the automatic algorithm should work, so you should
210 In most cases the automatic algorithm should work, so you should
206 rarely need to explicitly invoke /. One notable exception is if you
211 rarely need to explicitly invoke /. One notable exception is if you
207 are trying to call a function with a list of tuples as arguments (the
212 are trying to call a function with a list of tuples as arguments (the
208 parenthesis will confuse IPython):
213 parenthesis will confuse IPython):
209 In [1]: zip (1,2,3),(4,5,6) # won't work
214 In [1]: zip (1,2,3),(4,5,6) # won't work
210 but this will work:
215 but this will work:
211 In [2]: /zip (1,2,3),(4,5,6)
216 In [2]: /zip (1,2,3),(4,5,6)
212 ------> zip ((1,2,3),(4,5,6))
217 ------> zip ((1,2,3),(4,5,6))
213 Out[2]= [(1, 4), (2, 5), (3, 6)]
218 Out[2]= [(1, 4), (2, 5), (3, 6)]
214
219
215 IPython tells you that it has altered your command line by
220 IPython tells you that it has altered your command line by
216 displaying the new command line preceded by -->. e.g.:
221 displaying the new command line preceded by -->. e.g.:
217 In [18]: callable list
222 In [18]: callable list
218 -------> callable (list)
223 -------> callable (list)
219
224
220 2. Auto-Quoting
225 2. Auto-Quoting
221 You can force auto-quoting of a function's arguments by using ',' as
226 You can force auto-quoting of a function's arguments by using ',' as
222 the first character of a line. For example:
227 the first character of a line. For example:
223 In [1]: ,my_function /home/me # becomes my_function("/home/me")
228 In [1]: ,my_function /home/me # becomes my_function("/home/me")
224
229
225 If you use ';' instead, the whole argument is quoted as a single
230 If you use ';' instead, the whole argument is quoted as a single
226 string (while ',' splits on whitespace):
231 string (while ',' splits on whitespace):
227 In [2]: ,my_function a b c # becomes my_function("a","b","c")
232 In [2]: ,my_function a b c # becomes my_function("a","b","c")
228 In [3]: ;my_function a b c # becomes my_function("a b c")
233 In [3]: ;my_function a b c # becomes my_function("a b c")
229
234
230 Note that the ',' MUST be the first character on the line! This
235 Note that the ',' MUST be the first character on the line! This
231 won't work:
236 won't work:
232 In [4]: x = ,my_function /home/me # syntax error
237 In [4]: x = ,my_function /home/me # syntax error
233 """
238 """
234
239
235 interactive_usage_min = """\
240 interactive_usage_min = """\
236 An enhanced console for Python.
241 An enhanced console for Python.
237 Some of its features are:
242 Some of its features are:
238 - Readline support if the readline library is present.
243 - Readline support if the readline library is present.
239 - Tab completion in the local namespace.
244 - Tab completion in the local namespace.
240 - Logging of input, see command-line options.
245 - Logging of input, see command-line options.
241 - System shell escape via ! , eg !ls.
246 - System shell escape via ! , eg !ls.
242 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
247 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
243 - Keeps track of locally defined variables via %who, %whos.
248 - Keeps track of locally defined variables via %who, %whos.
244 - Show object information with a ? eg ?x or x? (use ?? for more info).
249 - Show object information with a ? eg ?x or x? (use ?? for more info).
245 """
250 """
246
251
247 quick_reference = r"""
252 quick_reference = r"""
248 IPython -- An enhanced Interactive Python - Quick Reference Card
253 IPython -- An enhanced Interactive Python - Quick Reference Card
249 ================================================================
254 ================================================================
250
255
251 obj?, obj?? : Get help, or more help for object (also works as
256 obj?, obj?? : Get help, or more help for object (also works as
252 ?obj, ??obj).
257 ?obj, ??obj).
253 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
258 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
254 %magic : Information about IPython's 'magic' % functions.
259 %magic : Information about IPython's 'magic' % functions.
255
260
256 Magic functions are prefixed by %, and typically take their arguments without
261 Magic functions are prefixed by %, and typically take their arguments without
257 parentheses, quotes or even commas for convenience.
262 parentheses, quotes or even commas for convenience.
258
263
259 Example magic function calls:
264 Example magic function calls:
260
265
261 %alias d ls -F : 'd' is now an alias for 'ls -F'
266 %alias d ls -F : 'd' is now an alias for 'ls -F'
262 alias d ls -F : Works if 'alias' not a python name
267 alias d ls -F : Works if 'alias' not a python name
263 alist = %alias : Get list of aliases to 'alist'
268 alist = %alias : Get list of aliases to 'alist'
264 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
269 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
265 %cd?? : See help AND source for magic %cd
270 %cd?? : See help AND source for magic %cd
266
271
267 System commands:
272 System commands:
268
273
269 !cp a.txt b/ : System command escape, calls os.system()
274 !cp a.txt b/ : System command escape, calls os.system()
270 cp a.txt b/ : after %rehashx, most system commands work without !
275 cp a.txt b/ : after %rehashx, most system commands work without !
271 cp ${f}.txt $bar : Variable expansion in magics and system commands
276 cp ${f}.txt $bar : Variable expansion in magics and system commands
272 files = !ls /usr : Capture sytem command output
277 files = !ls /usr : Capture sytem command output
273 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
278 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
274
279
275 History:
280 History:
276
281
277 _i, _ii, _iii : Previous, next previous, next next previous input
282 _i, _ii, _iii : Previous, next previous, next next previous input
278 _i4, _ih[2:5] : Input history line 4, lines 2-4
283 _i4, _ih[2:5] : Input history line 4, lines 2-4
279 exec _i81 : Execute input history line #81 again
284 exec _i81 : Execute input history line #81 again
280 %rep 81 : Edit input history line #81
285 %rep 81 : Edit input history line #81
281 _, __, ___ : previous, next previous, next next previous output
286 _, __, ___ : previous, next previous, next next previous output
282 _dh : Directory history
287 _dh : Directory history
283 _oh : Output history
288 _oh : Output history
284 %hist : Command history. '%hist -g foo' search history for 'foo'
289 %hist : Command history. '%hist -g foo' search history for 'foo'
285
290
286 Autocall:
291 Autocall:
287
292
288 f 1,2 : f(1,2)
293 f 1,2 : f(1,2) # Off by default, enable with %autocall magic.
289 /f 1,2 : f(1,2) (forced autoparen)
294 /f 1,2 : f(1,2) (forced autoparen)
290 ,f 1 2 : f("1","2")
295 ,f 1 2 : f("1","2")
291 ;f 1 2 : f("1 2")
296 ;f 1 2 : f("1 2")
292
297
293 Remember: TAB completion works in many contexts, not just file names
298 Remember: TAB completion works in many contexts, not just file names
294 or python names.
299 or python names.
295
300
296 The following magic functions are currently available:
301 The following magic functions are currently available:
297
302
298 """
303 """
299
304
300 gui_reference = """\
305 gui_reference = """\
301 ===============================
306 ===============================
302 The graphical IPython console
307 The graphical IPython console
303 ===============================
308 ===============================
304
309
305 This console is designed to emulate the look, feel and workflow of a terminal
310 This console is designed to emulate the look, feel and workflow of a terminal
306 environment, while adding a number of enhancements that are simply not possible
311 environment, while adding a number of enhancements that are simply not possible
307 in a real terminal, such as inline syntax highlighting, true multiline editing,
312 in a real terminal, such as inline syntax highlighting, true multiline editing,
308 inline graphics and much more.
313 inline graphics and much more.
309
314
310 This quick reference document contains the basic information you'll need to
315 This quick reference document contains the basic information you'll need to
311 know to make the most efficient use of it. For the various command line
316 know to make the most efficient use of it. For the various command line
312 options available at startup, type ``ipython qtconsole --help`` at the command line.
317 options available at startup, type ``ipython qtconsole --help`` at the command line.
313
318
314
319
315 Multiline editing
320 Multiline editing
316 =================
321 =================
317
322
318 The graphical console is capable of true multiline editing, but it also tries
323 The graphical console is capable of true multiline editing, but it also tries
319 to behave intuitively like a terminal when possible. If you are used to
324 to behave intuitively like a terminal when possible. If you are used to
320 IPyhton's old terminal behavior, you should find the transition painless, and
325 IPyhton's old terminal behavior, you should find the transition painless, and
321 once you learn a few basic keybindings it will be a much more efficient
326 once you learn a few basic keybindings it will be a much more efficient
322 environment.
327 environment.
323
328
324 For single expressions or indented blocks, the console behaves almost like the
329 For single expressions or indented blocks, the console behaves almost like the
325 terminal IPython: single expressions are immediately evaluated, and indented
330 terminal IPython: single expressions are immediately evaluated, and indented
326 blocks are evaluated once a single blank line is entered::
331 blocks are evaluated once a single blank line is entered::
327
332
328 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
333 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
329 Hello IPython!
334 Hello IPython!
330
335
331 In [2]: for i in range(10):
336 In [2]: for i in range(10):
332 ...: print i,
337 ...: print i,
333 ...:
338 ...:
334 0 1 2 3 4 5 6 7 8 9
339 0 1 2 3 4 5 6 7 8 9
335
340
336 If you want to enter more than one expression in a single input block
341 If you want to enter more than one expression in a single input block
337 (something not possible in the terminal), you can use ``Control-Enter`` at the
342 (something not possible in the terminal), you can use ``Control-Enter`` at the
338 end of your first line instead of ``Enter``. At that point the console goes
343 end of your first line instead of ``Enter``. At that point the console goes
339 into 'cell mode' and even if your inputs are not indented, it will continue
344 into 'cell mode' and even if your inputs are not indented, it will continue
340 accepting arbitrarily many lines until either you enter an extra blank line or
345 accepting arbitrarily many lines until either you enter an extra blank line or
341 you hit ``Shift-Enter`` (the key binding that forces execution). When a
346 you hit ``Shift-Enter`` (the key binding that forces execution). When a
342 multiline cell is entered, IPython analyzes it and executes its code producing
347 multiline cell is entered, IPython analyzes it and executes its code producing
343 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
348 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
344 cell is executed as if it was a script. An example should clarify this::
349 cell is executed as if it was a script. An example should clarify this::
345
350
346 In [3]: x=1 # Hit C-Enter here
351 In [3]: x=1 # Hit C-Enter here
347 ...: y=2 # from now on, regular Enter is sufficient
352 ...: y=2 # from now on, regular Enter is sufficient
348 ...: z=3
353 ...: z=3
349 ...: x**2 # This does *not* produce an Out[] value
354 ...: x**2 # This does *not* produce an Out[] value
350 ...: x+y+z # Only the last expression does
355 ...: x+y+z # Only the last expression does
351 ...:
356 ...:
352 Out[3]: 6
357 Out[3]: 6
353
358
354 The behavior where an extra blank line forces execution is only active if you
359 The behavior where an extra blank line forces execution is only active if you
355 are actually typing at the keyboard each line, and is meant to make it mimic
360 are actually typing at the keyboard each line, and is meant to make it mimic
356 the IPython terminal behavior. If you paste a long chunk of input (for example
361 the IPython terminal behavior. If you paste a long chunk of input (for example
357 a long script copied form an editor or web browser), it can contain arbitrarily
362 a long script copied form an editor or web browser), it can contain arbitrarily
358 many intermediate blank lines and they won't cause any problems. As always,
363 many intermediate blank lines and they won't cause any problems. As always,
359 you can then make it execute by appending a blank line *at the end* or hitting
364 you can then make it execute by appending a blank line *at the end* or hitting
360 ``Shift-Enter`` anywhere within the cell.
365 ``Shift-Enter`` anywhere within the cell.
361
366
362 With the up arrow key, you can retrieve previous blocks of input that contain
367 With the up arrow key, you can retrieve previous blocks of input that contain
363 multiple lines. You can move inside of a multiline cell like you would in any
368 multiple lines. You can move inside of a multiline cell like you would in any
364 text editor. When you want it executed, the simplest thing to do is to hit the
369 text editor. When you want it executed, the simplest thing to do is to hit the
365 force execution key, ``Shift-Enter`` (though you can also navigate to the end
370 force execution key, ``Shift-Enter`` (though you can also navigate to the end
366 and append a blank line by using ``Enter`` twice).
371 and append a blank line by using ``Enter`` twice).
367
372
368 If you've edited a multiline cell and accidentally navigate out of it with the
373 If you've edited a multiline cell and accidentally navigate out of it with the
369 up or down arrow keys, IPython will clear the cell and replace it with the
374 up or down arrow keys, IPython will clear the cell and replace it with the
370 contents of the one above or below that you navigated to. If this was an
375 contents of the one above or below that you navigated to. If this was an
371 accident and you want to retrieve the cell you were editing, use the Undo
376 accident and you want to retrieve the cell you were editing, use the Undo
372 keybinding, ``Control-z``.
377 keybinding, ``Control-z``.
373
378
374
379
375 Key bindings
380 Key bindings
376 ============
381 ============
377
382
378 The IPython console supports most of the basic Emacs line-oriented keybindings,
383 The IPython console supports most of the basic Emacs line-oriented keybindings,
379 in addition to some of its own.
384 in addition to some of its own.
380
385
381 The keybinding prefixes mean:
386 The keybinding prefixes mean:
382
387
383 - ``C``: Control
388 - ``C``: Control
384 - ``S``: Shift
389 - ``S``: Shift
385 - ``M``: Meta (typically the Alt key)
390 - ``M``: Meta (typically the Alt key)
386
391
387 The keybindings themselves are:
392 The keybindings themselves are:
388
393
389 - ``Enter``: insert new line (may cause execution, see above).
394 - ``Enter``: insert new line (may cause execution, see above).
390 - ``C-Enter``: *force* new line, *never* causes execution.
395 - ``C-Enter``: *force* new line, *never* causes execution.
391 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
396 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
392 - ``Up``: step backwards through the history.
397 - ``Up``: step backwards through the history.
393 - ``Down``: step forwards through the history.
398 - ``Down``: step forwards through the history.
394 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
399 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
395 - ``S-Down``: search forwards through the history.
400 - ``S-Down``: search forwards through the history.
396 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
401 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
397 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
402 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
398 - ``C-v``: paste text from clipboard.
403 - ``C-v``: paste text from clipboard.
399 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
404 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
400 - ``C-S-z``: redo.
405 - ``C-S-z``: redo.
401 - ``C-o``: move to 'other' area, between pager and terminal.
406 - ``C-o``: move to 'other' area, between pager and terminal.
402 - ``C-l``: clear terminal.
407 - ``C-l``: clear terminal.
403 - ``C-a``: go to beginning of line.
408 - ``C-a``: go to beginning of line.
404 - ``C-e``: go to end of line.
409 - ``C-e``: go to end of line.
405 - ``C-k``: kill from cursor to the end of the line.
410 - ``C-k``: kill from cursor to the end of the line.
406 - ``C-y``: yank (paste)
411 - ``C-y``: yank (paste)
407 - ``C-p``: previous line (like up arrow)
412 - ``C-p``: previous line (like up arrow)
408 - ``C-n``: next line (like down arrow)
413 - ``C-n``: next line (like down arrow)
409 - ``C-f``: forward (like right arrow)
414 - ``C-f``: forward (like right arrow)
410 - ``C-b``: back (like left arrow)
415 - ``C-b``: back (like left arrow)
411 - ``C-d``: delete next character.
416 - ``C-d``: delete next character.
412 - ``M-<``: move to the beginning of the input region.
417 - ``M-<``: move to the beginning of the input region.
413 - ``M->``: move to the end of the input region.
418 - ``M->``: move to the end of the input region.
414 - ``M-d``: delete next word.
419 - ``M-d``: delete next word.
415 - ``M-Backspace``: delete previous word.
420 - ``M-Backspace``: delete previous word.
416 - ``C-.``: force a kernel restart (a confirmation dialog appears).
421 - ``C-.``: force a kernel restart (a confirmation dialog appears).
417 - ``C-+``: increase font size.
422 - ``C-+``: increase font size.
418 - ``C--``: decrease font size.
423 - ``C--``: decrease font size.
419 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
424 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
420
425
421 The IPython pager
426 The IPython pager
422 =================
427 =================
423
428
424 IPython will show long blocks of text from many sources using a builtin pager.
429 IPython will show long blocks of text from many sources using a builtin pager.
425 You can control where this pager appears with the ``--paging`` command-line
430 You can control where this pager appears with the ``--paging`` command-line
426 flag:
431 flag:
427
432
428 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
433 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
429 must quit the pager to get back to the terminal (similar to how a pager such
434 must quit the pager to get back to the terminal (similar to how a pager such
430 as ``less`` or ``more`` works).
435 as ``less`` or ``more`` works).
431
436
432 - ``vsplit``: the console is made double-tall, and the pager appears on the
437 - ``vsplit``: the console is made double-tall, and the pager appears on the
433 bottom area when needed. You can view its contents while using the terminal.
438 bottom area when needed. You can view its contents while using the terminal.
434
439
435 - ``hsplit``: the console is made double-wide, and the pager appears on the
440 - ``hsplit``: the console is made double-wide, and the pager appears on the
436 right area when needed. You can view its contents while using the terminal.
441 right area when needed. You can view its contents while using the terminal.
437
442
438 - ``none``: the console never pages output.
443 - ``none``: the console never pages output.
439
444
440 If you use the vertical or horizontal paging modes, you can navigate between
445 If you use the vertical or horizontal paging modes, you can navigate between
441 terminal and pager as follows:
446 terminal and pager as follows:
442
447
443 - Tab key: goes from pager to terminal (but not the other way around).
448 - Tab key: goes from pager to terminal (but not the other way around).
444 - Control-o: goes from one to another always.
449 - Control-o: goes from one to another always.
445 - Mouse: click on either.
450 - Mouse: click on either.
446
451
447 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
452 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
448 focus on the pager area).
453 focus on the pager area).
449
454
450 Running subprocesses
455 Running subprocesses
451 ====================
456 ====================
452
457
453 The graphical IPython console uses the ``pexpect`` module to run subprocesses
458 The graphical IPython console uses the ``pexpect`` module to run subprocesses
454 when you type ``!command``. This has a number of advantages (true asynchronous
459 when you type ``!command``. This has a number of advantages (true asynchronous
455 output from subprocesses as well as very robust termination of rogue
460 output from subprocesses as well as very robust termination of rogue
456 subprocesses with ``Control-C``), as well as some limitations. The main
461 subprocesses with ``Control-C``), as well as some limitations. The main
457 limitation is that you can *not* interact back with the subprocess, so anything
462 limitation is that you can *not* interact back with the subprocess, so anything
458 that invokes a pager or expects you to type input into it will block and hang
463 that invokes a pager or expects you to type input into it will block and hang
459 (you can kill it with ``Control-C``).
464 (you can kill it with ``Control-C``).
460
465
461 We have provided as magics ``%less`` to page files (aliased to ``%more``),
466 We have provided as magics ``%less`` to page files (aliased to ``%more``),
462 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
467 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
463 most common commands you'd want to call in your subshell and that would cause
468 most common commands you'd want to call in your subshell and that would cause
464 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
469 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
465
470
466 Display
471 Display
467 =======
472 =======
468
473
469 The IPython console can now display objects in a variety of formats, including
474 The IPython console can now display objects in a variety of formats, including
470 HTML, PNG and SVG. This is accomplished using the display functions in
475 HTML, PNG and SVG. This is accomplished using the display functions in
471 ``IPython.core.display``::
476 ``IPython.core.display``::
472
477
473 In [4]: from IPython.core.display import display, display_html
478 In [4]: from IPython.core.display import display, display_html
474
479
475 In [5]: from IPython.core.display import display_png, display_svg
480 In [5]: from IPython.core.display import display_png, display_svg
476
481
477 Python objects can simply be passed to these functions and the appropriate
482 Python objects can simply be passed to these functions and the appropriate
478 representations will be displayed in the console as long as the objects know
483 representations will be displayed in the console as long as the objects know
479 how to compute those representations. The easiest way of teaching objects how
484 how to compute those representations. The easiest way of teaching objects how
480 to format themselves in various representations is to define special methods
485 to format themselves in various representations is to define special methods
481 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
486 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
482 can also be given custom formatter functions for various types::
487 can also be given custom formatter functions for various types::
483
488
484 In [6]: ip = get_ipython()
489 In [6]: ip = get_ipython()
485
490
486 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
491 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
487
492
488 In [8]: html_formatter.for_type(Foo, foo_to_html)
493 In [8]: html_formatter.for_type(Foo, foo_to_html)
489
494
490 For further details, see ``IPython.core.formatters``.
495 For further details, see ``IPython.core.formatters``.
491
496
492 Inline matplotlib graphics
497 Inline matplotlib graphics
493 ==========================
498 ==========================
494
499
495 The IPython console is capable of displaying matplotlib figures inline, in SVG
500 The IPython console is capable of displaying matplotlib figures inline, in SVG
496 or PNG format. If started with the ``pylab=inline``, then all figures are
501 or PNG format. If started with the ``pylab=inline``, then all figures are
497 rendered inline automatically (PNG by default). If started with ``--pylab``
502 rendered inline automatically (PNG by default). If started with ``--pylab``
498 or ``pylab=<your backend>``, then a GUI backend will be used, but IPython's
503 or ``pylab=<your backend>``, then a GUI backend will be used, but IPython's
499 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
504 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
500
505
501 In [9]: display(*getfigs()) # display all figures inline
506 In [9]: display(*getfigs()) # display all figures inline
502
507
503 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
508 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
504 """
509 """
505
510
506
511
507 quick_guide = """\
512 quick_guide = """\
508 ? -> Introduction and overview of IPython's features.
513 ? -> Introduction and overview of IPython's features.
509 %quickref -> Quick reference.
514 %quickref -> Quick reference.
510 help -> Python's own help system.
515 help -> Python's own help system.
511 object? -> Details about 'object', use 'object??' for extra details.
516 object? -> Details about 'object', use 'object??' for extra details.
512 """
517 """
513
518
514 gui_note = """\
519 gui_note = """\
515 %guiref -> A brief reference about the graphical user interface.
520 %guiref -> A brief reference about the graphical user interface.
516 """
521 """
517
522
518 default_banner_parts = [
523 default_banner_parts = [
519 'Python %s\n' % (sys.version.split('\n')[0],),
524 'Python %s\n' % (sys.version.split('\n')[0],),
520 'Type "copyright", "credits" or "license" for more information.\n\n',
525 'Type "copyright", "credits" or "license" for more information.\n\n',
521 'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
526 'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
522 quick_guide
527 quick_guide
523 ]
528 ]
524
529
525 default_gui_banner_parts = default_banner_parts + [gui_note]
530 default_gui_banner_parts = default_banner_parts + [gui_note]
526
531
527 default_banner = ''.join(default_banner_parts)
532 default_banner = ''.join(default_banner_parts)
528
533
529 default_gui_banner = ''.join(default_gui_banner_parts)
534 default_gui_banner = ''.join(default_gui_banner_parts)
@@ -1,1263 +1,1003 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 IPYTHON_DIR directory.
29 "profile_profilename" and are typically installed in the IPYTHON_DIR 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 Regular Options
47 Command-line Options
48 ---------------
48 --------------------
49
49
50 After the above threading options have been given, regular options can
50 To see the options IPython accepts, use ``ipython --help`` (and you probably
51 follow in any order. All options can be abbreviated to their shortest
51 should run the output through a pager such as ``ipython --help | less`` for
52 non-ambiguous form and are case-sensitive.
52 more convenient reading). This shows all the options that have a single-word
53
53 alias to control them, but IPython lets you configure all of its objects from
54 Most options can also be set from your configuration file. See the provided
54 the command-line by passing the full class name and a corresponding value; type
55 example for more details on what the options do. Options given at the command
55 ``ipython --help-all`` to see this full list. For example::
56 line override the values set in the configuration file.
56
57
57 ipython --pylab qt
58 All options with a [no] prepended can be specified in negated form
58
59 (--no-option instead of --option) to turn the feature off.
59 is equivalent to::
60
60
61 ``-h, --help`` print a help message and exit.
61 ipython --TerminalIPythonApp.pylab='qt'
62
62
63 ``--pylab, pylab=<name>``
63 Note that in the second form, you *must* use the equal sign, as the expression
64 See :ref:`Matplotlib support <matplotlib_support>`
64 is evaluated as an actual Python assignment. While in the above example the
65 for more details.
65 short form is more convenient, only the most common options have a short form,
66
66 while any configurable variable in IPython can be set at the command-line by
67 ``--autocall=<val>``
67 using the long form. This long form is the same syntax used in the
68 Make IPython automatically call any callable object even if you
68 configuration files, if you want to set these options permanently.
69 didn't type explicit parentheses. For example, 'str 43' becomes
70 'str(43)' automatically. The value can be '0' to disable the feature,
71 '1' for smart autocall, where it is not applied if there are no more
72 arguments on the line, and '2' for full autocall, where all callable
73 objects are automatically called (even if no arguments are
74 present). The default is '1'.
75
76 ``--[no-]autoindent``
77 Turn automatic indentation on/off.
78
79 ``--[no-]automagic``
80 make magic commands automatic (without needing their first character
81 to be %). Type %magic at the IPython prompt for more information.
82
83 ``--[no-]autoedit_syntax``
84 When a syntax error occurs after editing a file, automatically
85 open the file to the trouble causing line for convenient
86 fixing.
87
88 ``--[no-]banner``
89 Print the initial information banner (default on).
90
91 ``-c <command>``
92 execute the given command string. This is similar to the -c
93 option in the normal Python interpreter.
94
95 ``--cache-size=<n>``
96 size of the output cache (maximum number of entries to hold in
97 memory). The default is 1000, you can change it permanently in your
98 config file. Setting it to 0 completely disables the caching system,
99 and the minimum value accepted is 20 (if you provide a value less than
100 20, it is reset to 0 and a warning is issued) This limit is defined
101 because otherwise you'll spend more time re-flushing a too small cache
102 than working.
103
104 ``--classic``
105 Gives IPython a similar feel to the classic Python
106 prompt.
107
69
108 ``--colors=<scheme>``
109 Color scheme for prompts and exception reporting. Currently
110 implemented: NoColor, Linux and LightBG.
111
112 ``--[no-]color_info``
113 IPython can display information about objects via a set of functions,
114 and optionally can use colors for this, syntax highlighting source
115 code and various other elements. However, because this information is
116 passed through a pager (like 'less') and many pagers get confused with
117 color codes, this option is off by default. You can test it and turn
118 it on permanently in your configuration file if it works for you. As a
119 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
120 that in RedHat 7.2 doesn't.
121
122 Test it and turn it on permanently if it works with your
123 system. The magic function %color_info allows you to toggle this
124 interactively for testing.
125
126 ``--[no-]debug``
127 Show information about the loading process. Very useful to pin down
128 problems with your configuration files or to get details about
129 session restores.
130
131 ``--[no-]deep_reload``
132 IPython can use the deep_reload module which reloads changes in
133 modules recursively (it replaces the reload() function, so you don't
134 need to change anything to use it). deep_reload() forces a full
135 reload of modules whose code may have changed, which the default
136 reload() function does not.
137
138 When deep_reload is off, IPython will use the normal reload(),
139 but deep_reload will still be available as dreload(). This
140 feature is off by default [which means that you have both
141 normal reload() and dreload()].
142
143 .. this isn't currently working
144 .. ``--editor=<name>``
145 Which editor to use with the %edit command. By default,
146 IPython will honor your EDITOR environment variable (if not
147 set, vi is the Unix default and notepad the Windows one).
148 Since this editor is invoked on the fly by IPython and is
149 meant for editing small code snippets, you may want to use a
150 small, lightweight editor here (in case your default EDITOR is
151 something like Emacs).
152
153 ``--ipython_dir=<name>``
154 name of your IPython configuration directory IPYTHON_DIR. This
155 can also be specified through the environment variable
156 IPYTHON_DIR.
157
158 ``--logfile=<name>``
159 specify the name of your logfile.
160
161 This implies ``%logstart`` at the beginning of your session
162
163 generate a log file of all input. The file is named
164 ipython_log.py in your current directory (which prevents logs
165 from multiple IPython sessions from trampling each other). You
166 can use this to later restore a session by loading your
167 logfile with ``ipython -i ipython_log.py``
168
169 ``--logplay=<name>``
170
171 NOT AVAILABLE in 0.11
172
173 you can replay a previous log. For restoring a session as close as
174 possible to the state you left it in, use this option (don't just run
175 the logfile). With -logplay, IPython will try to reconstruct the
176 previous working environment in full, not just execute the commands in
177 the logfile.
178
179 When a session is restored, logging is automatically turned on
180 again with the name of the logfile it was invoked with (it is
181 read from the log header). So once you've turned logging on for
182 a session, you can quit IPython and reload it as many times as
183 you want and it will continue to log its history and restore
184 from the beginning every time.
185
186 Caveats: there are limitations in this option. The history
187 variables _i*,_* and _dh don't get restored properly. In the
188 future we will try to implement full session saving by writing
189 and retrieving a 'snapshot' of the memory state of IPython. But
190 our first attempts failed because of inherent limitations of
191 Python's Pickle module, so this may have to wait.
192
193 ``--[no-]messages``
194 Print messages which IPython collects about its startup
195 process (default on).
196
197 ``--[no-]pdb``
198 Automatically call the pdb debugger after every uncaught
199 exception. If you are used to debugging using pdb, this puts
200 you automatically inside of it after any call (either in
201 IPython or in code called by it) which triggers an exception
202 which goes uncaught.
203
204 ``--[no-]pprint``
205 ipython can optionally use the pprint (pretty printer) module
206 for displaying results. pprint tends to give a nicer display
207 of nested data structures. If you like it, you can turn it on
208 permanently in your config file (default off).
209
210 ``--profile=<name>``
211
212 Select the IPython profile by name.
213
214 This is a quick way to keep and load multiple
215 config files for different tasks, especially if you use the
216 include option of config files. You can keep a basic
217 :file:`IPYTHON_DIR/profile_default/ipython_config.py` file
218 and then have other 'profiles' which
219 include this one and load extra things for particular
220 tasks. For example:
221
222 1. $IPYTHON_DIR/profile_default : load basic things you always want.
223 2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules.
224 3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules.
225
226 Since it is possible to create an endless loop by having
227 circular file inclusions, IPython will stop if it reaches 15
228 recursive inclusions.
229
230 ``PromptManager.in_template=<string>``
231
232 Specify the string used for input prompts. Note that if you are using
233 numbered prompts, the number is represented with a '\#' in the
234 string. Don't forget to quote strings with spaces embedded in
235 them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>`
236 discusses in detail all the available escapes to customize your
237 prompts.
238
239 ``PromptManager.in2_template=<string>``
240 Similar to the previous option, but used for the continuation
241 prompts. The special sequence '\D' is similar to '\#', but
242 with all digits replaced dots (so you can have your
243 continuation prompt aligned with your input prompt). Default:
244 ' .\D.:' (note three spaces at the start for alignment with
245 'In [\#]').
246
247 ``PromptManager.out_template=<string>``
248 String used for output prompts, also uses numbers like
249 in_template. Default: 'Out[\#]:'
250
251 ``--quick``
252 start in bare bones mode (no config file loaded).
253
254 ``config_file=<name>``
255 name of your IPython resource configuration file. Normally
256 IPython loads ipython_config.py (from current directory) or
257 IPYTHON_DIR/profile_default.
258
259 If the loading of your config file fails, IPython starts with
260 a bare bones configuration (no modules loaded at all).
261
262 ``--[no-]readline``
263 use the readline library, which is needed to support name
264 completion and command history, among other things. It is
265 enabled by default, but may cause problems for users of
266 X/Emacs in Python comint or shell buffers.
267
268 Note that X/Emacs 'eterm' buffers (opened with M-x term) support
269 IPython's readline and syntax coloring fine, only 'emacs' (M-x
270 shell and C-c !) buffers do not.
271
272 ``--TerminalInteractiveShell.screen_length=<n>``
273 number of lines of your screen. This is used to control
274 printing of very long strings. Strings longer than this number
275 of lines will be sent through a pager instead of directly
276 printed.
277
278 The default value for this is 0, which means IPython will
279 auto-detect your screen size every time it needs to print certain
280 potentially long strings (this doesn't change the behavior of the
281 'print' keyword, it's only triggered internally). If for some
282 reason this isn't working well (it needs curses support), specify
283 it yourself. Otherwise don't change the default.
284
285 ``--TerminalInteractiveShell.separate_in=<string>``
286
287 separator before input prompts.
288 Default: '\n'
289
290 ``--TerminalInteractiveShell.separate_out=<string>``
291 separator before output prompts.
292 Default: nothing.
293
294 ``--TerminalInteractiveShell.separate_out2=<string>``
295 separator after output prompts.
296 Default: nothing.
297 For these three options, use the value 0 to specify no separator.
298
299 ``--nosep``
300 shorthand for setting the above separators to empty strings.
301
302 Simply removes all input/output separators.
303
304 ``--init``
305 allows you to initialize a profile dir for configuration when you
306 install a new version of IPython or want to use a new profile.
307 Since new versions may include new command line options or example
308 files, this copies updated config files. Note that you should probably
309 use %upgrade instead,it's a safer alternative.
310
311 ``--version`` print version information and exit.
312
313 ``--xmode=<modename>``
314
315 Mode for exception reporting.
316
317 Valid modes: Plain, Context and Verbose.
318
319 * Plain: similar to python's normal traceback printing.
320 * Context: prints 5 lines of context source code around each
321 line in the traceback.
322 * Verbose: similar to Context, but additionally prints the
323 variables currently visible where the exception happened
324 (shortening their strings if too long). This can potentially be
325 very slow, if you happen to have a huge data structure whose
326 string representation is complex to compute. Your computer may
327 appear to freeze for a while with cpu usage at 100%. If this
328 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
329 more than once).
330
70
331 Interactive use
71 Interactive use
332 ===============
72 ===============
333
73
334 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
335 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
336 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
337 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
338 prompt. What follows is a list of these.
78 prompt. What follows is a list of these.
339
79
340
80
341 Caution for Windows users
81 Caution for Windows users
342 -------------------------
82 -------------------------
343
83
344 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
345 terrible choice, because '\\' also represents the escape character in most
85 terrible choice, because '\\' also represents the escape character in most
346 modern programming languages, including Python. For this reason, using '/'
86 modern programming languages, including Python. For this reason, using '/'
347 character is recommended if you have problems with ``\``. However, in Windows
87 character is recommended if you have problems with ``\``. However, in Windows
348 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
349 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
350 like: ``%copy \opt/foo/bar.txt \tmp``
90 like: ``%copy \opt/foo/bar.txt \tmp``
351
91
352 .. _magic:
92 .. _magic:
353
93
354 Magic command system
94 Magic command system
355 --------------------
95 --------------------
356
96
357 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
358 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
359 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
360 prefixed with a % character, but parameters are given without
100 prefixed with a % character, but parameters are given without
361 parentheses or quotes.
101 parentheses or quotes.
362
102
363 Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it
103 Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it
364 exists.
104 exists.
365
105
366 If you have 'automagic' enabled (as it by default), you don't need
106 If you have 'automagic' enabled (as it by default), you don't need
367 to type in the % explicitly. IPython will scan its internal list of
107 to type in the % explicitly. IPython will scan its internal list of
368 magic functions and call one if it exists. With automagic on you can
108 magic functions and call one if it exists. With automagic on you can
369 then just type ``cd mydir`` to go to directory 'mydir'. The automagic
109 then just type ``cd mydir`` to go to directory 'mydir'. The automagic
370 system has the lowest possible precedence in name searches, so defining
110 system has the lowest possible precedence in name searches, so defining
371 an identifier with the same name as an existing magic function will
111 an identifier with the same name as an existing magic function will
372 shadow it for automagic use. You can still access the shadowed magic
112 shadow it for automagic use. You can still access the shadowed magic
373 function by explicitly using the % character at the beginning of the line.
113 function by explicitly using the % character at the beginning of the line.
374
114
375 An example (with automagic on) should clarify all this:
115 An example (with automagic on) should clarify all this:
376
116
377 .. sourcecode:: ipython
117 .. sourcecode:: ipython
378
118
379 In [1]: cd ipython # %cd is called by automagic
119 In [1]: cd ipython # %cd is called by automagic
380 /home/fperez/ipython
120 /home/fperez/ipython
381
121
382 In [2]: cd=1 # now cd is just a variable
122 In [2]: cd=1 # now cd is just a variable
383
123
384 In [3]: cd .. # and doesn't work as a function anymore
124 In [3]: cd .. # and doesn't work as a function anymore
385 File "<ipython-input-3-9fedb3aff56c>", line 1
125 File "<ipython-input-3-9fedb3aff56c>", line 1
386 cd ..
126 cd ..
387 ^
127 ^
388 SyntaxError: invalid syntax
128 SyntaxError: invalid syntax
389
129
390
130
391 In [4]: %cd .. # but %cd always works
131 In [4]: %cd .. # but %cd always works
392 /home/fperez
132 /home/fperez
393
133
394 In [5]: del cd # if you remove the cd variable, automagic works again
134 In [5]: del cd # if you remove the cd variable, automagic works again
395
135
396 In [6]: cd ipython
136 In [6]: cd ipython
397
137
398 /home/fperez/ipython
138 /home/fperez/ipython
399
139
400 You can define your own magic functions to extend the system. The
140 You can define your own magic functions to extend the system. The
401 following example defines a new magic command, %impall:
141 following example defines a new magic command, %impall:
402
142
403 .. sourcecode:: python
143 .. sourcecode:: python
404
144
405 ip = get_ipython()
145 ip = get_ipython()
406
146
407 def doimp(self, arg):
147 def doimp(self, arg):
408 ip = self.api
148 ip = self.api
409 ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) )
149 ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) )
410
150
411 ip.define_magic('impall', doimp)
151 ip.define_magic('impall', doimp)
412
152
413 Type ``%magic`` for more information, including a list of all available magic
153 Type ``%magic`` for more information, including a list of all available magic
414 functions at any time and their docstrings. You can also type
154 functions at any time and their docstrings. You can also type
415 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on
155 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on
416 the '?' system) to get information about any particular magic function you are
156 the '?' system) to get information about any particular magic function you are
417 interested in.
157 interested in.
418
158
419 The API documentation for the :mod:`IPython.core.magic` module contains the full
159 The API documentation for the :mod:`IPython.core.magic` module contains the full
420 docstrings of all currently available magic commands.
160 docstrings of all currently available magic commands.
421
161
422
162
423 Access to the standard Python help
163 Access to the standard Python help
424 ----------------------------------
164 ----------------------------------
425
165
426 Simply type ``help()`` to access Python's standard help system. You can
166 Simply type ``help()`` to access Python's standard help system. You can
427 also type ``help(object)`` for information about a given object, or
167 also type ``help(object)`` for information about a given object, or
428 ``help('keyword')`` for information on a keyword. You may need to configure your
168 ``help('keyword')`` for information on a keyword. You may need to configure your
429 PYTHONDOCS environment variable for this feature to work correctly.
169 PYTHONDOCS environment variable for this feature to work correctly.
430
170
431 .. _dynamic_object_info:
171 .. _dynamic_object_info:
432
172
433 Dynamic object information
173 Dynamic object information
434 --------------------------
174 --------------------------
435
175
436 Typing ``?word`` or ``word?`` prints detailed information about an object. If
176 Typing ``?word`` or ``word?`` prints detailed information about an object. If
437 certain strings in the object are too long (e.g. function signatures) they get
177 certain strings in the object are too long (e.g. function signatures) they get
438 snipped in the center for brevity. This system gives access variable types and
178 snipped in the center for brevity. This system gives access variable types and
439 values, docstrings, function prototypes and other useful information.
179 values, docstrings, function prototypes and other useful information.
440
180
441 If the information will not fit in the terminal, it is displayed in a pager
181 If the information will not fit in the terminal, it is displayed in a pager
442 (``less`` if available, otherwise a basic internal pager).
182 (``less`` if available, otherwise a basic internal pager).
443
183
444 Typing ``??word`` or ``word??`` gives access to the full information, including
184 Typing ``??word`` or ``word??`` gives access to the full information, including
445 the source code where possible. Long strings are not snipped.
185 the source code where possible. Long strings are not snipped.
446
186
447 The following magic functions are particularly useful for gathering
187 The following magic functions are particularly useful for gathering
448 information about your working environment. You can get more details by
188 information about your working environment. You can get more details by
449 typing ``%magic`` or querying them individually (``%function_name?``);
189 typing ``%magic`` or querying them individually (``%function_name?``);
450 this is just a summary:
190 this is just a summary:
451
191
452 * **%pdoc <object>**: Print (or run through a pager if too long) the
192 * **%pdoc <object>**: Print (or run through a pager if too long) the
453 docstring for an object. If the given object is a class, it will
193 docstring for an object. If the given object is a class, it will
454 print both the class and the constructor docstrings.
194 print both the class and the constructor docstrings.
455 * **%pdef <object>**: Print the definition header for any callable
195 * **%pdef <object>**: Print the definition header for any callable
456 object. If the object is a class, print the constructor information.
196 object. If the object is a class, print the constructor information.
457 * **%psource <object>**: Print (or run through a pager if too long)
197 * **%psource <object>**: Print (or run through a pager if too long)
458 the source code for an object.
198 the source code for an object.
459 * **%pfile <object>**: Show the entire source file where an object was
199 * **%pfile <object>**: Show the entire source file where an object was
460 defined via a pager, opening it at the line where the object
200 defined via a pager, opening it at the line where the object
461 definition begins.
201 definition begins.
462 * **%who/%whos**: These functions give information about identifiers
202 * **%who/%whos**: These functions give information about identifiers
463 you have defined interactively (not things you loaded or defined
203 you have defined interactively (not things you loaded or defined
464 in your configuration files). %who just prints a list of
204 in your configuration files). %who just prints a list of
465 identifiers and %whos prints a table with some basic details about
205 identifiers and %whos prints a table with some basic details about
466 each identifier.
206 each identifier.
467
207
468 Note that the dynamic object information functions (?/??, ``%pdoc``,
208 Note that the dynamic object information functions (?/??, ``%pdoc``,
469 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
209 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
470 directly on variables. For example, after doing ``import os``, you can use
210 directly on variables. For example, after doing ``import os``, you can use
471 ``os.path.abspath??``.
211 ``os.path.abspath??``.
472
212
473 .. _readline:
213 .. _readline:
474
214
475 Readline-based features
215 Readline-based features
476 -----------------------
216 -----------------------
477
217
478 These features require the GNU readline library, so they won't work if your
218 These features require the GNU readline library, so they won't work if your
479 Python installation lacks readline support. We will first describe the default
219 Python installation lacks readline support. We will first describe the default
480 behavior IPython uses, and then how to change it to suit your preferences.
220 behavior IPython uses, and then how to change it to suit your preferences.
481
221
482
222
483 Command line completion
223 Command line completion
484 +++++++++++++++++++++++
224 +++++++++++++++++++++++
485
225
486 At any time, hitting TAB will complete any available python commands or
226 At any time, hitting TAB will complete any available python commands or
487 variable names, and show you a list of the possible completions if
227 variable names, and show you a list of the possible completions if
488 there's no unambiguous one. It will also complete filenames in the
228 there's no unambiguous one. It will also complete filenames in the
489 current directory if no python names match what you've typed so far.
229 current directory if no python names match what you've typed so far.
490
230
491
231
492 Search command history
232 Search command history
493 ++++++++++++++++++++++
233 ++++++++++++++++++++++
494
234
495 IPython provides two ways for searching through previous input and thus
235 IPython provides two ways for searching through previous input and thus
496 reduce the need for repetitive typing:
236 reduce the need for repetitive typing:
497
237
498 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
238 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
499 (next,down) to search through only the history items that match
239 (next,down) to search through only the history items that match
500 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
240 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
501 prompt, they just behave like normal arrow keys.
241 prompt, they just behave like normal arrow keys.
502 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
242 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
503 searches your history for lines that contain what you've typed so
243 searches your history for lines that contain what you've typed so
504 far, completing as much as it can.
244 far, completing as much as it can.
505
245
506
246
507 Persistent command history across sessions
247 Persistent command history across sessions
508 ++++++++++++++++++++++++++++++++++++++++++
248 ++++++++++++++++++++++++++++++++++++++++++
509
249
510 IPython will save your input history when it leaves and reload it next
250 IPython will save your input history when it leaves and reload it next
511 time you restart it. By default, the history file is named
251 time you restart it. By default, the history file is named
512 $IPYTHON_DIR/profile_<name>/history.sqlite. This allows you to keep
252 $IPYTHON_DIR/profile_<name>/history.sqlite. This allows you to keep
513 separate histories related to various tasks: commands related to
253 separate histories related to various tasks: commands related to
514 numerical work will not be clobbered by a system shell history, for
254 numerical work will not be clobbered by a system shell history, for
515 example.
255 example.
516
256
517
257
518 Autoindent
258 Autoindent
519 ++++++++++
259 ++++++++++
520
260
521 IPython can recognize lines ending in ':' and indent the next line,
261 IPython can recognize lines ending in ':' and indent the next line,
522 while also un-indenting automatically after 'raise' or 'return'.
262 while also un-indenting automatically after 'raise' or 'return'.
523
263
524 This feature uses the readline library, so it will honor your
264 This feature uses the readline library, so it will honor your
525 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
265 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
526 to). Adding the following lines to your :file:`.inputrc` file can make
266 to). Adding the following lines to your :file:`.inputrc` file can make
527 indenting/unindenting more convenient (M-i indents, M-u unindents)::
267 indenting/unindenting more convenient (M-i indents, M-u unindents)::
528
268
529 $if Python
269 $if Python
530 "\M-i": " "
270 "\M-i": " "
531 "\M-u": "\d\d\d\d"
271 "\M-u": "\d\d\d\d"
532 $endif
272 $endif
533
273
534 Note that there are 4 spaces between the quote marks after "M-i" above.
274 Note that there are 4 spaces between the quote marks after "M-i" above.
535
275
536 .. warning::
276 .. warning::
537
277
538 Setting the above indents will cause problems with unicode text entry in
278 Setting the above indents will cause problems with unicode text entry in
539 the terminal.
279 the terminal.
540
280
541 .. warning::
281 .. warning::
542
282
543 Autoindent is ON by default, but it can cause problems with the pasting of
283 Autoindent is ON by default, but it can cause problems with the pasting of
544 multi-line indented code (the pasted code gets re-indented on each line). A
284 multi-line indented code (the pasted code gets re-indented on each line). A
545 magic function %autoindent allows you to toggle it on/off at runtime. You
285 magic function %autoindent allows you to toggle it on/off at runtime. You
546 can also disable it permanently on in your :file:`ipython_config.py` file
286 can also disable it permanently on in your :file:`ipython_config.py` file
547 (set TerminalInteractiveShell.autoindent=False).
287 (set TerminalInteractiveShell.autoindent=False).
548
288
549 If you want to paste multiple lines in the terminal, it is recommended that
289 If you want to paste multiple lines in the terminal, it is recommended that
550 you use ``%paste``.
290 you use ``%paste``.
551
291
552
292
553 Customizing readline behavior
293 Customizing readline behavior
554 +++++++++++++++++++++++++++++
294 +++++++++++++++++++++++++++++
555
295
556 All these features are based on the GNU readline library, which has an
296 All these features are based on the GNU readline library, which has an
557 extremely customizable interface. Normally, readline is configured via a
297 extremely customizable interface. Normally, readline is configured via a
558 file which defines the behavior of the library; the details of the
298 file which defines the behavior of the library; the details of the
559 syntax for this can be found in the readline documentation available
299 syntax for this can be found in the readline documentation available
560 with your system or on the Internet. IPython doesn't read this file (if
300 with your system or on the Internet. IPython doesn't read this file (if
561 it exists) directly, but it does support passing to readline valid
301 it exists) directly, but it does support passing to readline valid
562 options via a simple interface. In brief, you can customize readline by
302 options via a simple interface. In brief, you can customize readline by
563 setting the following options in your configuration file (note
303 setting the following options in your configuration file (note
564 that these options can not be specified at the command line):
304 that these options can not be specified at the command line):
565
305
566 * **readline_parse_and_bind**: this holds a list of strings to be executed
306 * **readline_parse_and_bind**: this holds a list of strings to be executed
567 via a readline.parse_and_bind() command. The syntax for valid commands
307 via a readline.parse_and_bind() command. The syntax for valid commands
568 of this kind can be found by reading the documentation for the GNU
308 of this kind can be found by reading the documentation for the GNU
569 readline library, as these commands are of the kind which readline
309 readline library, as these commands are of the kind which readline
570 accepts in its configuration file.
310 accepts in its configuration file.
571 * **readline_remove_delims**: a string of characters to be removed
311 * **readline_remove_delims**: a string of characters to be removed
572 from the default word-delimiters list used by readline, so that
312 from the default word-delimiters list used by readline, so that
573 completions may be performed on strings which contain them. Do not
313 completions may be performed on strings which contain them. Do not
574 change the default value unless you know what you're doing.
314 change the default value unless you know what you're doing.
575
315
576 You will find the default values in your configuration file.
316 You will find the default values in your configuration file.
577
317
578
318
579 Session logging and restoring
319 Session logging and restoring
580 -----------------------------
320 -----------------------------
581
321
582 You can log all input from a session either by starting IPython with the
322 You can log all input from a session either by starting IPython with the
583 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
323 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
584 or by activating the logging at any moment with the magic function %logstart.
324 or by activating the logging at any moment with the magic function %logstart.
585
325
586 Log files can later be reloaded by running them as scripts and IPython
326 Log files can later be reloaded by running them as scripts and IPython
587 will attempt to 'replay' the log by executing all the lines in it, thus
327 will attempt to 'replay' the log by executing all the lines in it, thus
588 restoring the state of a previous session. This feature is not quite
328 restoring the state of a previous session. This feature is not quite
589 perfect, but can still be useful in many cases.
329 perfect, but can still be useful in many cases.
590
330
591 The log files can also be used as a way to have a permanent record of
331 The log files can also be used as a way to have a permanent record of
592 any code you wrote while experimenting. Log files are regular text files
332 any code you wrote while experimenting. Log files are regular text files
593 which you can later open in your favorite text editor to extract code or
333 which you can later open in your favorite text editor to extract code or
594 to 'clean them up' before using them to replay a session.
334 to 'clean them up' before using them to replay a session.
595
335
596 The `%logstart` function for activating logging in mid-session is used as
336 The `%logstart` function for activating logging in mid-session is used as
597 follows::
337 follows::
598
338
599 %logstart [log_name [log_mode]]
339 %logstart [log_name [log_mode]]
600
340
601 If no name is given, it defaults to a file named 'ipython_log.py' in your
341 If no name is given, it defaults to a file named 'ipython_log.py' in your
602 current working directory, in 'rotate' mode (see below).
342 current working directory, in 'rotate' mode (see below).
603
343
604 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
344 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
605 history up to that point and then continues logging.
345 history up to that point and then continues logging.
606
346
607 %logstart takes a second optional parameter: logging mode. This can be
347 %logstart takes a second optional parameter: logging mode. This can be
608 one of (note that the modes are given unquoted):
348 one of (note that the modes are given unquoted):
609
349
610 * [over:] overwrite existing log_name.
350 * [over:] overwrite existing log_name.
611 * [backup:] rename (if exists) to log_name~ and start log_name.
351 * [backup:] rename (if exists) to log_name~ and start log_name.
612 * [append:] well, that says it.
352 * [append:] well, that says it.
613 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
353 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
614
354
615 The %logoff and %logon functions allow you to temporarily stop and
355 The %logoff and %logon functions allow you to temporarily stop and
616 resume logging to a file which had previously been started with
356 resume logging to a file which had previously been started with
617 %logstart. They will fail (with an explanation) if you try to use them
357 %logstart. They will fail (with an explanation) if you try to use them
618 before logging has been started.
358 before logging has been started.
619
359
620 .. _system_shell_access:
360 .. _system_shell_access:
621
361
622 System shell access
362 System shell access
623 -------------------
363 -------------------
624
364
625 Any input line beginning with a ! character is passed verbatim (minus
365 Any input line beginning with a ! character is passed verbatim (minus
626 the !, of course) to the underlying operating system. For example,
366 the !, of course) to the underlying operating system. For example,
627 typing ``!ls`` will run 'ls' in the current directory.
367 typing ``!ls`` will run 'ls' in the current directory.
628
368
629 Manual capture of command output
369 Manual capture of command output
630 --------------------------------
370 --------------------------------
631
371
632 You can assign the result of a system command to a Python variable with the
372 You can assign the result of a system command to a Python variable with the
633 syntax ``myfiles = !ls``. This gets machine readable output from stdout
373 syntax ``myfiles = !ls``. This gets machine readable output from stdout
634 (e.g. without colours), and splits on newlines. To explicitly get this sort of
374 (e.g. without colours), and splits on newlines. To explicitly get this sort of
635 output without assigning to a variable, use two exclamation marks (``!!ls``) or
375 output without assigning to a variable, use two exclamation marks (``!!ls``) or
636 the ``%sx`` magic command.
376 the ``%sx`` magic command.
637
377
638 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
378 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
639 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
379 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
640 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
380 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
641 See :ref:`string_lists` for details.
381 See :ref:`string_lists` for details.
642
382
643 IPython also allows you to expand the value of python variables when
383 IPython also allows you to expand the value of python variables when
644 making system calls. Wrap variables or expressions in {braces}::
384 making system calls. Wrap variables or expressions in {braces}::
645
385
646 In [1]: pyvar = 'Hello world'
386 In [1]: pyvar = 'Hello world'
647 In [2]: !echo "A python variable: {pyvar}"
387 In [2]: !echo "A python variable: {pyvar}"
648 A python variable: Hello world
388 A python variable: Hello world
649 In [3]: import math
389 In [3]: import math
650 In [4]: x = 8
390 In [4]: x = 8
651 In [5]: !echo {math.factorial(x)}
391 In [5]: !echo {math.factorial(x)}
652 40320
392 40320
653
393
654 For simple cases, you can alternatively prepend $ to a variable name::
394 For simple cases, you can alternatively prepend $ to a variable name::
655
395
656 In [6]: !echo $sys.argv
396 In [6]: !echo $sys.argv
657 [/home/fperez/usr/bin/ipython]
397 [/home/fperez/usr/bin/ipython]
658 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
398 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
659 A system variable: /home/fperez
399 A system variable: /home/fperez
660
400
661 System command aliases
401 System command aliases
662 ----------------------
402 ----------------------
663
403
664 The %alias magic function allows you to define magic functions which are in fact
404 The %alias magic function allows you to define magic functions which are in fact
665 system shell commands. These aliases can have parameters.
405 system shell commands. These aliases can have parameters.
666
406
667 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
407 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
668
408
669 Then, typing ``alias_name params`` will execute the system command 'cmd
409 Then, typing ``alias_name params`` will execute the system command 'cmd
670 params' (from your underlying operating system).
410 params' (from your underlying operating system).
671
411
672 You can also define aliases with parameters using %s specifiers (one per
412 You can also define aliases with parameters using %s specifiers (one per
673 parameter). The following example defines the parts function as an
413 parameter). The following example defines the parts function as an
674 alias to the command 'echo first %s second %s' where each %s will be
414 alias to the command 'echo first %s second %s' where each %s will be
675 replaced by a positional parameter to the call to %parts::
415 replaced by a positional parameter to the call to %parts::
676
416
677 In [1]: %alias parts echo first %s second %s
417 In [1]: %alias parts echo first %s second %s
678 In [2]: parts A B
418 In [2]: parts A B
679 first A second B
419 first A second B
680 In [3]: parts A
420 In [3]: parts A
681 ERROR: Alias <parts> requires 2 arguments, 1 given.
421 ERROR: Alias <parts> requires 2 arguments, 1 given.
682
422
683 If called with no parameters, %alias prints the table of currently
423 If called with no parameters, %alias prints the table of currently
684 defined aliases.
424 defined aliases.
685
425
686 The %rehashx magic allows you to load your entire $PATH as
426 The %rehashx magic allows you to load your entire $PATH as
687 ipython aliases. See its docstring for further details.
427 ipython aliases. See its docstring for further details.
688
428
689
429
690 .. _dreload:
430 .. _dreload:
691
431
692 Recursive reload
432 Recursive reload
693 ----------------
433 ----------------
694
434
695 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
435 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
696 module: changes made to any of its dependencies will be reloaded without
436 module: changes made to any of its dependencies will be reloaded without
697 having to exit. To start using it, do::
437 having to exit. To start using it, do::
698
438
699 from IPython.lib.deepreload import reload as dreload
439 from IPython.lib.deepreload import reload as dreload
700
440
701
441
702 Verbose and colored exception traceback printouts
442 Verbose and colored exception traceback printouts
703 -------------------------------------------------
443 -------------------------------------------------
704
444
705 IPython provides the option to see very detailed exception tracebacks,
445 IPython provides the option to see very detailed exception tracebacks,
706 which can be especially useful when debugging large programs. You can
446 which can be especially useful when debugging large programs. You can
707 run any Python file with the %run function to benefit from these
447 run any Python file with the %run function to benefit from these
708 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
448 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
709 be colored (if your terminal supports it) which makes them much easier
449 be colored (if your terminal supports it) which makes them much easier
710 to parse visually.
450 to parse visually.
711
451
712 See the magic xmode and colors functions for details (just type %magic).
452 See the magic xmode and colors functions for details (just type %magic).
713
453
714 These features are basically a terminal version of Ka-Ping Yee's cgitb
454 These features are basically a terminal version of Ka-Ping Yee's cgitb
715 module, now part of the standard Python library.
455 module, now part of the standard Python library.
716
456
717
457
718 .. _input_caching:
458 .. _input_caching:
719
459
720 Input caching system
460 Input caching system
721 --------------------
461 --------------------
722
462
723 IPython offers numbered prompts (In/Out) with input and output caching
463 IPython offers numbered prompts (In/Out) with input and output caching
724 (also referred to as 'input history'). All input is saved and can be
464 (also referred to as 'input history'). All input is saved and can be
725 retrieved as variables (besides the usual arrow key recall), in
465 retrieved as variables (besides the usual arrow key recall), in
726 addition to the %rep magic command that brings a history entry
466 addition to the %rep magic command that brings a history entry
727 up for editing on the next command line.
467 up for editing on the next command line.
728
468
729 The following GLOBAL variables always exist (so don't overwrite them!):
469 The following GLOBAL variables always exist (so don't overwrite them!):
730
470
731 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
471 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
732 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
472 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
733 overwrite In with a variable of your own, you can remake the assignment to the
473 overwrite In with a variable of your own, you can remake the assignment to the
734 internal list with a simple ``In=_ih``.
474 internal list with a simple ``In=_ih``.
735
475
736 Additionally, global variables named _i<n> are dynamically created (<n>
476 Additionally, global variables named _i<n> are dynamically created (<n>
737 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
477 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
738
478
739 For example, what you typed at prompt 14 is available as _i14, _ih[14]
479 For example, what you typed at prompt 14 is available as _i14, _ih[14]
740 and In[14].
480 and In[14].
741
481
742 This allows you to easily cut and paste multi line interactive prompts
482 This allows you to easily cut and paste multi line interactive prompts
743 by printing them out: they print like a clean string, without prompt
483 by printing them out: they print like a clean string, without prompt
744 characters. You can also manipulate them like regular variables (they
484 characters. You can also manipulate them like regular variables (they
745 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
485 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
746 contents of input prompt 9.
486 contents of input prompt 9.
747
487
748 You can also re-execute multiple lines of input easily by using the
488 You can also re-execute multiple lines of input easily by using the
749 magic %rerun or %macro functions. The macro system also allows you to re-execute
489 magic %rerun or %macro functions. The macro system also allows you to re-execute
750 previous lines which include magic function calls (which require special
490 previous lines which include magic function calls (which require special
751 processing). Type %macro? for more details on the macro system.
491 processing). Type %macro? for more details on the macro system.
752
492
753 A history function %hist allows you to see any part of your input
493 A history function %hist allows you to see any part of your input
754 history by printing a range of the _i variables.
494 history by printing a range of the _i variables.
755
495
756 You can also search ('grep') through your history by typing
496 You can also search ('grep') through your history by typing
757 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
497 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
758 etc. You can bring history entries listed by '%hist -g' up for editing
498 etc. You can bring history entries listed by '%hist -g' up for editing
759 with the %recall command, or run them immediately with %rerun.
499 with the %recall command, or run them immediately with %rerun.
760
500
761 .. _output_caching:
501 .. _output_caching:
762
502
763 Output caching system
503 Output caching system
764 ---------------------
504 ---------------------
765
505
766 For output that is returned from actions, a system similar to the input
506 For output that is returned from actions, a system similar to the input
767 cache exists but using _ instead of _i. Only actions that produce a
507 cache exists but using _ instead of _i. Only actions that produce a
768 result (NOT assignments, for example) are cached. If you are familiar
508 result (NOT assignments, for example) are cached. If you are familiar
769 with Mathematica, IPython's _ variables behave exactly like
509 with Mathematica, IPython's _ variables behave exactly like
770 Mathematica's % variables.
510 Mathematica's % variables.
771
511
772 The following GLOBAL variables always exist (so don't overwrite them!):
512 The following GLOBAL variables always exist (so don't overwrite them!):
773
513
774 * [_] (a single underscore) : stores previous output, like Python's
514 * [_] (a single underscore) : stores previous output, like Python's
775 default interpreter.
515 default interpreter.
776 * [__] (two underscores): next previous.
516 * [__] (two underscores): next previous.
777 * [___] (three underscores): next-next previous.
517 * [___] (three underscores): next-next previous.
778
518
779 Additionally, global variables named _<n> are dynamically created (<n>
519 Additionally, global variables named _<n> are dynamically created (<n>
780 being the prompt counter), such that the result of output <n> is always
520 being the prompt counter), such that the result of output <n> is always
781 available as _<n> (don't use the angle brackets, just the number, e.g.
521 available as _<n> (don't use the angle brackets, just the number, e.g.
782 _21).
522 _21).
783
523
784 These variables are also stored in a global dictionary (not a
524 These variables are also stored in a global dictionary (not a
785 list, since it only has entries for lines which returned a result)
525 list, since it only has entries for lines which returned a result)
786 available under the names _oh and Out (similar to _ih and In). So the
526 available under the names _oh and Out (similar to _ih and In). So the
787 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
527 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
788 accidentally overwrite the Out variable you can recover it by typing
528 accidentally overwrite the Out variable you can recover it by typing
789 'Out=_oh' at the prompt.
529 'Out=_oh' at the prompt.
790
530
791 This system obviously can potentially put heavy memory demands on your
531 This system obviously can potentially put heavy memory demands on your
792 system, since it prevents Python's garbage collector from removing any
532 system, since it prevents Python's garbage collector from removing any
793 previously computed results. You can control how many results are kept
533 previously computed results. You can control how many results are kept
794 in memory with the option (at the command line or in your configuration
534 in memory with the option (at the command line or in your configuration
795 file) cache_size. If you set it to 0, the whole system is completely
535 file) cache_size. If you set it to 0, the whole system is completely
796 disabled and the prompts revert to the classic '>>>' of normal Python.
536 disabled and the prompts revert to the classic '>>>' of normal Python.
797
537
798
538
799 Directory history
539 Directory history
800 -----------------
540 -----------------
801
541
802 Your history of visited directories is kept in the global list _dh, and
542 Your history of visited directories is kept in the global list _dh, and
803 the magic %cd command can be used to go to any entry in that list. The
543 the magic %cd command can be used to go to any entry in that list. The
804 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
544 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
805 conveniently view the directory history.
545 conveniently view the directory history.
806
546
807
547
808 Automatic parentheses and quotes
548 Automatic parentheses and quotes
809 --------------------------------
549 --------------------------------
810
550
811 These features were adapted from Nathan Gray's LazyPython. They are
551 These features were adapted from Nathan Gray's LazyPython. They are
812 meant to allow less typing for common situations.
552 meant to allow less typing for common situations.
813
553
814
554
815 Automatic parentheses
555 Automatic parentheses
816 +++++++++++++++++++++
556 +++++++++++++++++++++
817
557
818 Callable objects (i.e. functions, methods, etc) can be invoked like this
558 Callable objects (i.e. functions, methods, etc) can be invoked like this
819 (notice the commas between the arguments)::
559 (notice the commas between the arguments)::
820
560
821 In [1]: callable_ob arg1, arg2, arg3
561 In [1]: callable_ob arg1, arg2, arg3
822 ------> callable_ob(arg1, arg2, arg3)
562 ------> callable_ob(arg1, arg2, arg3)
823
563
824 You can force automatic parentheses by using '/' as the first character
564 You can force automatic parentheses by using '/' as the first character
825 of a line. For example::
565 of a line. For example::
826
566
827 In [2]: /globals # becomes 'globals()'
567 In [2]: /globals # becomes 'globals()'
828
568
829 Note that the '/' MUST be the first character on the line! This won't work::
569 Note that the '/' MUST be the first character on the line! This won't work::
830
570
831 In [3]: print /globals # syntax error
571 In [3]: print /globals # syntax error
832
572
833 In most cases the automatic algorithm should work, so you should rarely
573 In most cases the automatic algorithm should work, so you should rarely
834 need to explicitly invoke /. One notable exception is if you are trying
574 need to explicitly invoke /. One notable exception is if you are trying
835 to call a function with a list of tuples as arguments (the parenthesis
575 to call a function with a list of tuples as arguments (the parenthesis
836 will confuse IPython)::
576 will confuse IPython)::
837
577
838 In [4]: zip (1,2,3),(4,5,6) # won't work
578 In [4]: zip (1,2,3),(4,5,6) # won't work
839
579
840 but this will work::
580 but this will work::
841
581
842 In [5]: /zip (1,2,3),(4,5,6)
582 In [5]: /zip (1,2,3),(4,5,6)
843 ------> zip ((1,2,3),(4,5,6))
583 ------> zip ((1,2,3),(4,5,6))
844 Out[5]: [(1, 4), (2, 5), (3, 6)]
584 Out[5]: [(1, 4), (2, 5), (3, 6)]
845
585
846 IPython tells you that it has altered your command line by displaying
586 IPython tells you that it has altered your command line by displaying
847 the new command line preceded by ->. e.g.::
587 the new command line preceded by ->. e.g.::
848
588
849 In [6]: callable list
589 In [6]: callable list
850 ------> callable(list)
590 ------> callable(list)
851
591
852
592
853 Automatic quoting
593 Automatic quoting
854 +++++++++++++++++
594 +++++++++++++++++
855
595
856 You can force automatic quoting of a function's arguments by using ','
596 You can force automatic quoting of a function's arguments by using ','
857 or ';' as the first character of a line. For example::
597 or ';' as the first character of a line. For example::
858
598
859 In [1]: ,my_function /home/me # becomes my_function("/home/me")
599 In [1]: ,my_function /home/me # becomes my_function("/home/me")
860
600
861 If you use ';' the whole argument is quoted as a single string, while ',' splits
601 If you use ';' the whole argument is quoted as a single string, while ',' splits
862 on whitespace::
602 on whitespace::
863
603
864 In [2]: ,my_function a b c # becomes my_function("a","b","c")
604 In [2]: ,my_function a b c # becomes my_function("a","b","c")
865
605
866 In [3]: ;my_function a b c # becomes my_function("a b c")
606 In [3]: ;my_function a b c # becomes my_function("a b c")
867
607
868 Note that the ',' or ';' MUST be the first character on the line! This
608 Note that the ',' or ';' MUST be the first character on the line! This
869 won't work::
609 won't work::
870
610
871 In [4]: x = ,my_function /home/me # syntax error
611 In [4]: x = ,my_function /home/me # syntax error
872
612
873 IPython as your default Python environment
613 IPython as your default Python environment
874 ==========================================
614 ==========================================
875
615
876 Python honors the environment variable PYTHONSTARTUP and will execute at
616 Python honors the environment variable PYTHONSTARTUP and will execute at
877 startup the file referenced by this variable. If you put the following code at
617 startup the file referenced by this variable. If you put the following code at
878 the end of that file, then IPython will be your working environment anytime you
618 the end of that file, then IPython will be your working environment anytime you
879 start Python::
619 start Python::
880
620
881 from IPython.frontend.terminal.ipapp import launch_new_instance
621 from IPython.frontend.terminal.ipapp import launch_new_instance
882 launch_new_instance()
622 launch_new_instance()
883 raise SystemExit
623 raise SystemExit
884
624
885 The ``raise SystemExit`` is needed to exit Python when
625 The ``raise SystemExit`` is needed to exit Python when
886 it finishes, otherwise you'll be back at the normal Python '>>>'
626 it finishes, otherwise you'll be back at the normal Python '>>>'
887 prompt.
627 prompt.
888
628
889 This is probably useful to developers who manage multiple Python
629 This is probably useful to developers who manage multiple Python
890 versions and don't want to have correspondingly multiple IPython
630 versions and don't want to have correspondingly multiple IPython
891 versions. Note that in this mode, there is no way to pass IPython any
631 versions. Note that in this mode, there is no way to pass IPython any
892 command-line options, as those are trapped first by Python itself.
632 command-line options, as those are trapped first by Python itself.
893
633
894 .. _Embedding:
634 .. _Embedding:
895
635
896 Embedding IPython
636 Embedding IPython
897 =================
637 =================
898
638
899 It is possible to start an IPython instance inside your own Python
639 It is possible to start an IPython instance inside your own Python
900 programs. This allows you to evaluate dynamically the state of your
640 programs. This allows you to evaluate dynamically the state of your
901 code, operate with your variables, analyze them, etc. Note however that
641 code, operate with your variables, analyze them, etc. Note however that
902 any changes you make to values while in the shell do not propagate back
642 any changes you make to values while in the shell do not propagate back
903 to the running code, so it is safe to modify your values because you
643 to the running code, so it is safe to modify your values because you
904 won't break your code in bizarre ways by doing so.
644 won't break your code in bizarre ways by doing so.
905
645
906 .. note::
646 .. note::
907
647
908 At present, trying to embed IPython from inside IPython causes problems. Run
648 At present, trying to embed IPython from inside IPython causes problems. Run
909 the code samples below outside IPython.
649 the code samples below outside IPython.
910
650
911 This feature allows you to easily have a fully functional python
651 This feature allows you to easily have a fully functional python
912 environment for doing object introspection anywhere in your code with a
652 environment for doing object introspection anywhere in your code with a
913 simple function call. In some cases a simple print statement is enough,
653 simple function call. In some cases a simple print statement is enough,
914 but if you need to do more detailed analysis of a code fragment this
654 but if you need to do more detailed analysis of a code fragment this
915 feature can be very valuable.
655 feature can be very valuable.
916
656
917 It can also be useful in scientific computing situations where it is
657 It can also be useful in scientific computing situations where it is
918 common to need to do some automatic, computationally intensive part and
658 common to need to do some automatic, computationally intensive part and
919 then stop to look at data, plots, etc.
659 then stop to look at data, plots, etc.
920 Opening an IPython instance will give you full access to your data and
660 Opening an IPython instance will give you full access to your data and
921 functions, and you can resume program execution once you are done with
661 functions, and you can resume program execution once you are done with
922 the interactive part (perhaps to stop again later, as many times as
662 the interactive part (perhaps to stop again later, as many times as
923 needed).
663 needed).
924
664
925 The following code snippet is the bare minimum you need to include in
665 The following code snippet is the bare minimum you need to include in
926 your Python programs for this to work (detailed examples follow later)::
666 your Python programs for this to work (detailed examples follow later)::
927
667
928 from IPython import embed
668 from IPython import embed
929
669
930 embed() # this call anywhere in your program will start IPython
670 embed() # this call anywhere in your program will start IPython
931
671
932 You can run embedded instances even in code which is itself being run at
672 You can run embedded instances even in code which is itself being run at
933 the IPython interactive prompt with '%run <filename>'. Since it's easy
673 the IPython interactive prompt with '%run <filename>'. Since it's easy
934 to get lost as to where you are (in your top-level IPython or in your
674 to get lost as to where you are (in your top-level IPython or in your
935 embedded one), it's a good idea in such cases to set the in/out prompts
675 embedded one), it's a good idea in such cases to set the in/out prompts
936 to something different for the embedded instances. The code examples
676 to something different for the embedded instances. The code examples
937 below illustrate this.
677 below illustrate this.
938
678
939 You can also have multiple IPython instances in your program and open
679 You can also have multiple IPython instances in your program and open
940 them separately, for example with different options for data
680 them separately, for example with different options for data
941 presentation. If you close and open the same instance multiple times,
681 presentation. If you close and open the same instance multiple times,
942 its prompt counters simply continue from each execution to the next.
682 its prompt counters simply continue from each execution to the next.
943
683
944 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
684 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
945 module for more details on the use of this system.
685 module for more details on the use of this system.
946
686
947 The following sample file illustrating how to use the embedding
687 The following sample file illustrating how to use the embedding
948 functionality is provided in the examples directory as example-embed.py.
688 functionality is provided in the examples directory as example-embed.py.
949 It should be fairly self-explanatory:
689 It should be fairly self-explanatory:
950
690
951 .. literalinclude:: ../../examples/core/example-embed.py
691 .. literalinclude:: ../../examples/core/example-embed.py
952 :language: python
692 :language: python
953
693
954 Once you understand how the system functions, you can use the following
694 Once you understand how the system functions, you can use the following
955 code fragments in your programs which are ready for cut and paste:
695 code fragments in your programs which are ready for cut and paste:
956
696
957 .. literalinclude:: ../../examples/core/example-embed-short.py
697 .. literalinclude:: ../../examples/core/example-embed-short.py
958 :language: python
698 :language: python
959
699
960 Using the Python debugger (pdb)
700 Using the Python debugger (pdb)
961 ===============================
701 ===============================
962
702
963 Running entire programs via pdb
703 Running entire programs via pdb
964 -------------------------------
704 -------------------------------
965
705
966 pdb, the Python debugger, is a powerful interactive debugger which
706 pdb, the Python debugger, is a powerful interactive debugger which
967 allows you to step through code, set breakpoints, watch variables,
707 allows you to step through code, set breakpoints, watch variables,
968 etc. IPython makes it very easy to start any script under the control
708 etc. IPython makes it very easy to start any script under the control
969 of pdb, regardless of whether you have wrapped it into a 'main()'
709 of pdb, regardless of whether you have wrapped it into a 'main()'
970 function or not. For this, simply type '%run -d myscript' at an
710 function or not. For this, simply type '%run -d myscript' at an
971 IPython prompt. See the %run command's documentation (via '%run?' or
711 IPython prompt. See the %run command's documentation (via '%run?' or
972 in Sec. magic_ for more details, including how to control where pdb
712 in Sec. magic_ for more details, including how to control where pdb
973 will stop execution first.
713 will stop execution first.
974
714
975 For more information on the use of the pdb debugger, read the included
715 For more information on the use of the pdb debugger, read the included
976 pdb.doc file (part of the standard Python distribution). On a stock
716 pdb.doc file (part of the standard Python distribution). On a stock
977 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
717 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
978 easiest way to read it is by using the help() function of the pdb module
718 easiest way to read it is by using the help() function of the pdb module
979 as follows (in an IPython prompt)::
719 as follows (in an IPython prompt)::
980
720
981 In [1]: import pdb
721 In [1]: import pdb
982 In [2]: pdb.help()
722 In [2]: pdb.help()
983
723
984 This will load the pdb.doc document in a file viewer for you automatically.
724 This will load the pdb.doc document in a file viewer for you automatically.
985
725
986
726
987 Automatic invocation of pdb on exceptions
727 Automatic invocation of pdb on exceptions
988 -----------------------------------------
728 -----------------------------------------
989
729
990 IPython, if started with the ``--pdb`` option (or if the option is set in
730 IPython, if started with the ``--pdb`` option (or if the option is set in
991 your config file) can call the Python pdb debugger every time your code
731 your config file) can call the Python pdb debugger every time your code
992 triggers an uncaught exception. This feature
732 triggers an uncaught exception. This feature
993 can also be toggled at any time with the %pdb magic command. This can be
733 can also be toggled at any time with the %pdb magic command. This can be
994 extremely useful in order to find the origin of subtle bugs, because pdb
734 extremely useful in order to find the origin of subtle bugs, because pdb
995 opens up at the point in your code which triggered the exception, and
735 opens up at the point in your code which triggered the exception, and
996 while your program is at this point 'dead', all the data is still
736 while your program is at this point 'dead', all the data is still
997 available and you can walk up and down the stack frame and understand
737 available and you can walk up and down the stack frame and understand
998 the origin of the problem.
738 the origin of the problem.
999
739
1000 Furthermore, you can use these debugging facilities both with the
740 Furthermore, you can use these debugging facilities both with the
1001 embedded IPython mode and without IPython at all. For an embedded shell
741 embedded IPython mode and without IPython at all. For an embedded shell
1002 (see sec. Embedding_), simply call the constructor with
742 (see sec. Embedding_), simply call the constructor with
1003 ``--pdb`` in the argument string and pdb will automatically be called if an
743 ``--pdb`` in the argument string and pdb will automatically be called if an
1004 uncaught exception is triggered by your code.
744 uncaught exception is triggered by your code.
1005
745
1006 For stand-alone use of the feature in your programs which do not use
746 For stand-alone use of the feature in your programs which do not use
1007 IPython at all, put the following lines toward the top of your 'main'
747 IPython at all, put the following lines toward the top of your 'main'
1008 routine::
748 routine::
1009
749
1010 import sys
750 import sys
1011 from IPython.core import ultratb
751 from IPython.core import ultratb
1012 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
752 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
1013 color_scheme='Linux', call_pdb=1)
753 color_scheme='Linux', call_pdb=1)
1014
754
1015 The mode keyword can be either 'Verbose' or 'Plain', giving either very
755 The mode keyword can be either 'Verbose' or 'Plain', giving either very
1016 detailed or normal tracebacks respectively. The color_scheme keyword can
756 detailed or normal tracebacks respectively. The color_scheme keyword can
1017 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
757 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
1018 options which can be set in IPython with ``--colors`` and ``--xmode``.
758 options which can be set in IPython with ``--colors`` and ``--xmode``.
1019
759
1020 This will give any of your programs detailed, colored tracebacks with
760 This will give any of your programs detailed, colored tracebacks with
1021 automatic invocation of pdb.
761 automatic invocation of pdb.
1022
762
1023
763
1024 Extensions for syntax processing
764 Extensions for syntax processing
1025 ================================
765 ================================
1026
766
1027 This isn't for the faint of heart, because the potential for breaking
767 This isn't for the faint of heart, because the potential for breaking
1028 things is quite high. But it can be a very powerful and useful feature.
768 things is quite high. But it can be a very powerful and useful feature.
1029 In a nutshell, you can redefine the way IPython processes the user input
769 In a nutshell, you can redefine the way IPython processes the user input
1030 line to accept new, special extensions to the syntax without needing to
770 line to accept new, special extensions to the syntax without needing to
1031 change any of IPython's own code.
771 change any of IPython's own code.
1032
772
1033 In the IPython/extensions directory you will find some examples
773 In the IPython/extensions directory you will find some examples
1034 supplied, which we will briefly describe now. These can be used 'as is'
774 supplied, which we will briefly describe now. These can be used 'as is'
1035 (and both provide very useful functionality), or you can use them as a
775 (and both provide very useful functionality), or you can use them as a
1036 starting point for writing your own extensions.
776 starting point for writing your own extensions.
1037
777
1038 .. _pasting_with_prompts:
778 .. _pasting_with_prompts:
1039
779
1040 Pasting of code starting with Python or IPython prompts
780 Pasting of code starting with Python or IPython prompts
1041 -------------------------------------------------------
781 -------------------------------------------------------
1042
782
1043 IPython is smart enough to filter out input prompts, be they plain Python ones
783 IPython is smart enough to filter out input prompts, be they plain Python ones
1044 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
784 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
1045 therefore copy and paste from existing interactive sessions without worry.
785 therefore copy and paste from existing interactive sessions without worry.
1046
786
1047 The following is a 'screenshot' of how things work, copying an example from the
787 The following is a 'screenshot' of how things work, copying an example from the
1048 standard Python tutorial::
788 standard Python tutorial::
1049
789
1050 In [1]: >>> # Fibonacci series:
790 In [1]: >>> # Fibonacci series:
1051
791
1052 In [2]: ... # the sum of two elements defines the next
792 In [2]: ... # the sum of two elements defines the next
1053
793
1054 In [3]: ... a, b = 0, 1
794 In [3]: ... a, b = 0, 1
1055
795
1056 In [4]: >>> while b < 10:
796 In [4]: >>> while b < 10:
1057 ...: ... print b
797 ...: ... print b
1058 ...: ... a, b = b, a+b
798 ...: ... a, b = b, a+b
1059 ...:
799 ...:
1060 1
800 1
1061 1
801 1
1062 2
802 2
1063 3
803 3
1064 5
804 5
1065 8
805 8
1066
806
1067 And pasting from IPython sessions works equally well::
807 And pasting from IPython sessions works equally well::
1068
808
1069 In [1]: In [5]: def f(x):
809 In [1]: In [5]: def f(x):
1070 ...: ...: "A simple function"
810 ...: ...: "A simple function"
1071 ...: ...: return x**2
811 ...: ...: return x**2
1072 ...: ...:
812 ...: ...:
1073
813
1074 In [2]: f(3)
814 In [2]: f(3)
1075 Out[2]: 9
815 Out[2]: 9
1076
816
1077 .. _gui_support:
817 .. _gui_support:
1078
818
1079 GUI event loop support
819 GUI event loop support
1080 ======================
820 ======================
1081
821
1082 .. versionadded:: 0.11
822 .. versionadded:: 0.11
1083 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
823 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
1084
824
1085 IPython has excellent support for working interactively with Graphical User
825 IPython has excellent support for working interactively with Graphical User
1086 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
826 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
1087 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
827 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
1088 is extremely robust compared to our previous thread-based version. The
828 is extremely robust compared to our previous thread-based version. The
1089 advantages of this are:
829 advantages of this are:
1090
830
1091 * GUIs can be enabled and disabled dynamically at runtime.
831 * GUIs can be enabled and disabled dynamically at runtime.
1092 * The active GUI can be switched dynamically at runtime.
832 * The active GUI can be switched dynamically at runtime.
1093 * In some cases, multiple GUIs can run simultaneously with no problems.
833 * In some cases, multiple GUIs can run simultaneously with no problems.
1094 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
834 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
1095 all of these things.
835 all of these things.
1096
836
1097 For users, enabling GUI event loop integration is simple. You simple use the
837 For users, enabling GUI event loop integration is simple. You simple use the
1098 ``%gui`` magic as follows::
838 ``%gui`` magic as follows::
1099
839
1100 %gui [GUINAME]
840 %gui [GUINAME]
1101
841
1102 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
842 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
1103 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
843 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
1104
844
1105 Thus, to use wxPython interactively and create a running :class:`wx.App`
845 Thus, to use wxPython interactively and create a running :class:`wx.App`
1106 object, do::
846 object, do::
1107
847
1108 %gui wx
848 %gui wx
1109
849
1110 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
850 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
1111 see :ref:`this section <matplotlib_support>`.
851 see :ref:`this section <matplotlib_support>`.
1112
852
1113 For developers that want to use IPython's GUI event loop integration in the
853 For developers that want to use IPython's GUI event loop integration in the
1114 form of a library, these capabilities are exposed in library form in the
854 form of a library, these capabilities are exposed in library form in the
1115 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
855 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
1116 Interested developers should see the module docstrings for more information,
856 Interested developers should see the module docstrings for more information,
1117 but there are a few points that should be mentioned here.
857 but there are a few points that should be mentioned here.
1118
858
1119 First, the ``PyOSInputHook`` approach only works in command line settings
859 First, the ``PyOSInputHook`` approach only works in command line settings
1120 where readline is activated. The integration with various eventloops
860 where readline is activated. The integration with various eventloops
1121 is handled somewhat differently (and more simply) when using the standalone
861 is handled somewhat differently (and more simply) when using the standalone
1122 kernel, as in the qtconsole and notebook.
862 kernel, as in the qtconsole and notebook.
1123
863
1124 Second, when using the ``PyOSInputHook`` approach, a GUI application should
864 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1125 *not* start its event loop. Instead all of this is handled by the
865 *not* start its event loop. Instead all of this is handled by the
1126 ``PyOSInputHook``. This means that applications that are meant to be used both
866 ``PyOSInputHook``. This means that applications that are meant to be used both
1127 in IPython and as standalone apps need to have special code to detects how the
867 in IPython and as standalone apps need to have special code to detects how the
1128 application is being run. We highly recommend using IPython's support for this.
868 application is being run. We highly recommend using IPython's support for this.
1129 Since the details vary slightly between toolkits, we point you to the various
869 Since the details vary slightly between toolkits, we point you to the various
1130 examples in our source directory :file:`docs/examples/lib` that demonstrate
870 examples in our source directory :file:`docs/examples/lib` that demonstrate
1131 these capabilities.
871 these capabilities.
1132
872
1133 .. warning::
873 .. warning::
1134
874
1135 The WX version of this is currently broken. While ``--pylab=wx`` works
875 The WX version of this is currently broken. While ``--pylab=wx`` works
1136 fine, standalone WX apps do not. See
876 fine, standalone WX apps do not. See
1137 https://github.com/ipython/ipython/issues/645 for details of our progress on
877 https://github.com/ipython/ipython/issues/645 for details of our progress on
1138 this issue.
878 this issue.
1139
879
1140
880
1141 Third, unlike previous versions of IPython, we no longer "hijack" (replace
881 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1142 them with no-ops) the event loops. This is done to allow applications that
882 them with no-ops) the event loops. This is done to allow applications that
1143 actually need to run the real event loops to do so. This is often needed to
883 actually need to run the real event loops to do so. This is often needed to
1144 process pending events at critical points.
884 process pending events at critical points.
1145
885
1146 Finally, we also have a number of examples in our source directory
886 Finally, we also have a number of examples in our source directory
1147 :file:`docs/examples/lib` that demonstrate these capabilities.
887 :file:`docs/examples/lib` that demonstrate these capabilities.
1148
888
1149 PyQt and PySide
889 PyQt and PySide
1150 ---------------
890 ---------------
1151
891
1152 .. attempt at explanation of the complete mess that is Qt support
892 .. attempt at explanation of the complete mess that is Qt support
1153
893
1154 When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
894 When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
1155 PyQt4 or PySide. There are three options for configuration here, because
895 PyQt4 or PySide. There are three options for configuration here, because
1156 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
896 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
1157 Python 2, and the more natural v2, which is the only API supported by PySide.
897 Python 2, and the more natural v2, which is the only API supported by PySide.
1158 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
898 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
1159 uses v2, but you can still use any interface in your code, since the
899 uses v2, but you can still use any interface in your code, since the
1160 Qt frontend is in a different process.
900 Qt frontend is in a different process.
1161
901
1162 The default will be to import PyQt4 without configuration of the APIs, thus
902 The default will be to import PyQt4 without configuration of the APIs, thus
1163 matching what most applications would expect. It will fall back of PySide if
903 matching what most applications would expect. It will fall back of PySide if
1164 PyQt4 is unavailable.
904 PyQt4 is unavailable.
1165
905
1166 If specified, IPython will respect the environment variable ``QT_API`` used
906 If specified, IPython will respect the environment variable ``QT_API`` used
1167 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
907 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
1168 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
908 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
1169 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
909 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
1170 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
910 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
1171
911
1172 If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
912 If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
1173 will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
913 will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
1174 the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
914 the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
1175 IPython will always use PyQt4 without setting the v2 APIs, since neither v2
915 IPython will always use PyQt4 without setting the v2 APIs, since neither v2
1176 PyQt nor PySide work.
916 PyQt nor PySide work.
1177
917
1178 .. warning::
918 .. warning::
1179
919
1180 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
920 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
1181 to work with IPython's qt integration, because otherwise PyQt4 will be
921 to work with IPython's qt integration, because otherwise PyQt4 will be
1182 loaded in an incompatible mode.
922 loaded in an incompatible mode.
1183
923
1184 It also means that you must *not* have ``QT_API`` set if you want to
924 It also means that you must *not* have ``QT_API`` set if you want to
1185 use ``--gui=qt`` with code that requires PyQt4 API v1.
925 use ``--gui=qt`` with code that requires PyQt4 API v1.
1186
926
1187
927
1188 .. _matplotlib_support:
928 .. _matplotlib_support:
1189
929
1190 Plotting with matplotlib
930 Plotting with matplotlib
1191 ========================
931 ========================
1192
932
1193 `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
933 `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
1194 can produce plots on screen using a variety of GUI toolkits, including Tk,
934 can produce plots on screen using a variety of GUI toolkits, including Tk,
1195 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
935 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
1196 scientific computing, all with a syntax compatible with that of the popular
936 scientific computing, all with a syntax compatible with that of the popular
1197 Matlab program.
937 Matlab program.
1198
938
1199 To start IPython with matplotlib support, use the ``--pylab`` switch. If no
939 To start IPython with matplotlib support, use the ``--pylab`` switch. If no
1200 arguments are given, IPython will automatically detect your choice of
940 arguments are given, IPython will automatically detect your choice of
1201 matplotlib backend. You can also request a specific backend with
941 matplotlib backend. You can also request a specific backend with
1202 ``--pylab=backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk',
942 ``--pylab=backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk',
1203 'osx'.
943 'osx'.
1204
944
1205 .. _Matplotlib: http://matplotlib.sourceforge.net
945 .. _Matplotlib: http://matplotlib.sourceforge.net
1206
946
1207 .. _interactive_demos:
947 .. _interactive_demos:
1208
948
1209 Interactive demos with IPython
949 Interactive demos with IPython
1210 ==============================
950 ==============================
1211
951
1212 IPython ships with a basic system for running scripts interactively in
952 IPython ships with a basic system for running scripts interactively in
1213 sections, useful when presenting code to audiences. A few tags embedded
953 sections, useful when presenting code to audiences. A few tags embedded
1214 in comments (so that the script remains valid Python code) divide a file
954 in comments (so that the script remains valid Python code) divide a file
1215 into separate blocks, and the demo can be run one block at a time, with
955 into separate blocks, and the demo can be run one block at a time, with
1216 IPython printing (with syntax highlighting) the block before executing
956 IPython printing (with syntax highlighting) the block before executing
1217 it, and returning to the interactive prompt after each block. The
957 it, and returning to the interactive prompt after each block. The
1218 interactive namespace is updated after each block is run with the
958 interactive namespace is updated after each block is run with the
1219 contents of the demo's namespace.
959 contents of the demo's namespace.
1220
960
1221 This allows you to show a piece of code, run it and then execute
961 This allows you to show a piece of code, run it and then execute
1222 interactively commands based on the variables just created. Once you
962 interactively commands based on the variables just created. Once you
1223 want to continue, you simply execute the next block of the demo. The
963 want to continue, you simply execute the next block of the demo. The
1224 following listing shows the markup necessary for dividing a script into
964 following listing shows the markup necessary for dividing a script into
1225 sections for execution as a demo:
965 sections for execution as a demo:
1226
966
1227 .. literalinclude:: ../../examples/lib/example-demo.py
967 .. literalinclude:: ../../examples/lib/example-demo.py
1228 :language: python
968 :language: python
1229
969
1230 In order to run a file as a demo, you must first make a Demo object out
970 In order to run a file as a demo, you must first make a Demo object out
1231 of it. If the file is named myscript.py, the following code will make a
971 of it. If the file is named myscript.py, the following code will make a
1232 demo::
972 demo::
1233
973
1234 from IPython.lib.demo import Demo
974 from IPython.lib.demo import Demo
1235
975
1236 mydemo = Demo('myscript.py')
976 mydemo = Demo('myscript.py')
1237
977
1238 This creates the mydemo object, whose blocks you run one at a time by
978 This creates the mydemo object, whose blocks you run one at a time by
1239 simply calling the object with no arguments. If you have autocall active
979 simply calling the object with no arguments. If you have autocall active
1240 in IPython (the default), all you need to do is type::
980 in IPython (the default), all you need to do is type::
1241
981
1242 mydemo
982 mydemo
1243
983
1244 and IPython will call it, executing each block. Demo objects can be
984 and IPython will call it, executing each block. Demo objects can be
1245 restarted, you can move forward or back skipping blocks, re-execute the
985 restarted, you can move forward or back skipping blocks, re-execute the
1246 last block, etc. Simply use the Tab key on a demo object to see its
986 last block, etc. Simply use the Tab key on a demo object to see its
1247 methods, and call '?' on them to see their docstrings for more usage
987 methods, and call '?' on them to see their docstrings for more usage
1248 details. In addition, the demo module itself contains a comprehensive
988 details. In addition, the demo module itself contains a comprehensive
1249 docstring, which you can access via::
989 docstring, which you can access via::
1250
990
1251 from IPython.lib import demo
991 from IPython.lib import demo
1252
992
1253 demo?
993 demo?
1254
994
1255 Limitations: It is important to note that these demos are limited to
995 Limitations: It is important to note that these demos are limited to
1256 fairly simple uses. In particular, you cannot break up sections within
996 fairly simple uses. In particular, you cannot break up sections within
1257 indented code (loops, if statements, function definitions, etc.)
997 indented code (loops, if statements, function definitions, etc.)
1258 Supporting something like this would basically require tracking the
998 Supporting something like this would basically require tracking the
1259 internal execution state of the Python interpreter, so only top-level
999 internal execution state of the Python interpreter, so only top-level
1260 divisions are allowed. If you want to be able to open an IPython
1000 divisions are allowed. If you want to be able to open an IPython
1261 instance at an arbitrary point in a program, you can use IPython's
1001 instance at an arbitrary point in a program, you can use IPython's
1262 embedding facilities, see :func:`IPython.embed` for details.
1002 embedding facilities, see :func:`IPython.embed` for details.
1263
1003
General Comments 0
You need to be logged in to leave comments. Login now