##// END OF EJS Templates
Make interactive_usage a bit more rst friendly...
Carlos Cordoba -
Show More
@@ -1,548 +1,565 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 `IPYTHONDIR` directory, and there
42 This file is typically installed in the `IPYTHONDIR` 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 $IPYTHONDIR/profile_default. For Linux users,
44 directory will be located in $IPYTHONDIR/profile_default. For Linux users,
45 IPYTHONDIR defaults to `$HOME/.config/ipython`, and for other Unix systems
45 IPYTHONDIR 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 `IPYTHONDIR/profile_default/ipython_config.py`
53 and start editing `IPYTHONDIR/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 `IPYTHONDIR`, you can change its default location by creating an
56 `IPYTHONDIR`, 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
78 * Access to the standard Python help. As of Python 2.1, a help system is
79 * 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
80 available with access to object docstrings and the Python manuals. Simply
80 type 'help' (no quotes) to access it.
81 type 'help' (no quotes) to access it.
81
82
82 * Magic commands: type %magic for information on the magic subsystem.
83 * Magic commands: type %magic for information on the magic subsystem.
83
84
84 * System command aliases, via the %alias command or the configuration file(s).
85 * System command aliases, via the %alias command or the configuration file(s).
85
86
86 * Dynamic object information:
87 * Dynamic object information:
87
88
88 Typing ?word or word? prints detailed information about an object. If
89 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
90 certain strings in the object are too long (docstrings, code, etc.) they get
90 snipped in the center for brevity.
91 snipped in the center for brevity.
91
92
92 Typing ??word or word?? gives access to the full information without
93 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
94 snipping long strings. Long strings are sent to the screen through the less
94 pager if longer than the screen, printed otherwise.
95 pager if longer than the screen, printed otherwise.
95
96
96 The ?/?? system gives access to the full source code for any object (if
97 The ?/?? system gives access to the full source code for any object (if
97 available), shows function prototypes and other useful information.
98 available), shows function prototypes and other useful information.
98
99
99 If you just want to see an object's docstring, type '%pdoc object' (without
100 If you just want to see an object's docstring, type '%pdoc object' (without
100 quotes, and without % if you have automagic on).
101 quotes, and without % if you have automagic on).
101
102
102 Both %pdoc and ?/?? give you access to documentation even on things which are
103 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,
104 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
105 type os.path.abspath??. The magic functions %pdef, %source and %file operate
105 similarly.
106 similarly.
106
107
107 * Completion in the local namespace, by typing TAB at the prompt.
108 * Completion in the local namespace, by typing TAB at the prompt.
108
109
109 At any time, hitting tab will complete any available python commands or
110 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
111 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.
112 no unambiguous one. It will also complete filenames in the current directory.
112
113
113 This feature requires the readline and rlcomplete modules, so it won't work
114 This feature requires the readline and rlcomplete modules, so it won't work
114 if your Python lacks readline support (such as under Windows).
115 if your Python lacks readline support (such as under Windows).
115
116
116 * Search previous command history in two ways (also requires readline):
117 * Search previous command history in two ways (also requires readline):
117
118
118 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
119 - 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
120 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
121 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
121 normal arrow keys.
122 normal arrow keys.
122
123
123 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
124 - 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
125 your history for lines that match what you've typed so far, completing as
125 much as it can.
126 much as it can.
126
127
127 - %hist: search history by index (this does *not* require readline).
128 - %hist: search history by index (this does *not* require readline).
128
129
129 * Persistent command history across sessions.
130 * Persistent command history across sessions.
130
131
131 * Logging of input with the ability to save and restore a working session.
132 * Logging of input with the ability to save and restore a working session.
132
133
133 * System escape with !. Typing !ls will run 'ls' in the current directory.
134 * System escape with !. Typing !ls will run 'ls' in the current directory.
134
135
135 * The reload command does a 'deep' reload of a module: changes made to the
136 * 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.
137 module since you imported will actually be available without having to exit.
137
138
138 * Verbose and colored exception traceback printouts. See the magic xmode and
139 * Verbose and colored exception traceback printouts. See the magic xmode and
139 xcolor functions for details (just type %magic).
140 xcolor functions for details (just type %magic).
140
141
141 * Input caching system:
142 * Input caching system:
142
143
143 IPython offers numbered prompts (In/Out) with input and output caching. All
144 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
145 input is saved and can be retrieved as variables (besides the usual arrow
145 key recall).
146 key recall).
146
147
147 The following GLOBAL variables always exist (so don't overwrite them!):
148 The following GLOBAL variables always exist (so don't overwrite them!):
148 _i: stores previous input.
149 _i: stores previous input.
149 _ii: next previous.
150 _ii: next previous.
150 _iii: next-next previous.
151 _iii: next-next previous.
151 _ih : a list of all input _ih[n] is the input from line n.
152 _ih : a list of all input _ih[n] is the input from line n.
152
153
153 Additionally, global variables named _i<n> are dynamically created (<n>
154 Additionally, global variables named _i<n> are dynamically created (<n>
154 being the prompt counter), such that _i<n> == _ih[<n>]
155 being the prompt counter), such that _i<n> == _ih[<n>]
155
156
156 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
157 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
157
158
158 You can create macros which contain multiple input lines from this history,
159 You can create macros which contain multiple input lines from this history,
159 for later re-execution, with the %macro function.
160 for later re-execution, with the %macro function.
160
161
161 The history function %hist allows you to see any part of your input history
162 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
163 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
164 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.
165 because they aren't really valid Python code, so you can't exec them.
165
166
166 * Output caching system:
167 * Output caching system:
167
168
168 For output that is returned from actions, a system similar to the input
169 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
170 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
171 (NOT assignments, for example) are cached. If you are familiar with
171 Mathematica, IPython's _ variables behave exactly like Mathematica's %
172 Mathematica, IPython's _ variables behave exactly like Mathematica's %
172 variables.
173 variables.
173
174
174 The following GLOBAL variables always exist (so don't overwrite them!):
175 The following GLOBAL variables always exist (so don't overwrite them!):
175 _ (one underscore): previous output.
176 _ (one underscore): previous output.
176 __ (two underscores): next previous.
177 __ (two underscores): next previous.
177 ___ (three underscores): next-next previous.
178 ___ (three underscores): next-next previous.
178
179
179 Global variables named _<n> are dynamically created (<n> being the prompt
180 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>.
181 counter), such that the result of output <n> is always available as _<n>.
181
182
182 Finally, a global dictionary named _oh exists with entries for all lines
183 Finally, a global dictionary named _oh exists with entries for all lines
183 which generated output.
184 which generated output.
184
185
185 * Directory history:
186 * Directory history:
186
187
187 Your history of visited directories is kept in the global list _dh, and the
188 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.
189 magic %cd command can be used to go to any entry in that list.
189
190
190 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
191 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
191
192
192 1. Auto-parentheses
193 1. Auto-parentheses
194
193 Callable objects (i.e. functions, methods, etc) can be invoked like
195 Callable objects (i.e. functions, methods, etc) can be invoked like
194 this (notice the commas between the arguments):
196 this (notice the commas between the arguments)::
197
195 In [1]: callable_ob arg1, arg2, arg3
198 In [1]: callable_ob arg1, arg2, arg3
196 and the input will be translated to this:
199
197 ------> callable_ob(arg1, arg2, arg3)
200 and the input will be translated to this::
201
202 callable_ob(arg1, arg2, arg3)
203
198 This feature is off by default (in rare cases it can produce
204 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
205 undesirable side-effects), but you can activate it at the command-line
200 by starting IPython with `--autocall 1`, set it permanently in your
206 by starting IPython with `--autocall 1`, set it permanently in your
201 configuration file, or turn on at runtime with `%autocall 1`.
207 configuration file, or turn on at runtime with `%autocall 1`.
202
208
203 You can force auto-parentheses by using '/' as the first character
209 You can force auto-parentheses by using '/' as the first character
204 of a line. For example:
210 of a line. For example::
211
205 In [1]: /globals # becomes 'globals()'
212 In [1]: /globals # becomes 'globals()'
213
206 Note that the '/' MUST be the first character on the line! This
214 Note that the '/' MUST be the first character on the line! This
207 won't work:
215 won't work::
216
208 In [2]: print /globals # syntax error
217 In [2]: print /globals # syntax error
209
218
210 In most cases the automatic algorithm should work, so you should
219 In most cases the automatic algorithm should work, so you should
211 rarely need to explicitly invoke /. One notable exception is if you
220 rarely need to explicitly invoke /. One notable exception is if you
212 are trying to call a function with a list of tuples as arguments (the
221 are trying to call a function with a list of tuples as arguments (the
213 parenthesis will confuse IPython):
222 parenthesis will confuse IPython)::
223
214 In [1]: zip (1,2,3),(4,5,6) # won't work
224 In [1]: zip (1,2,3),(4,5,6) # won't work
215 but this will work:
225
226 but this will work::
227
216 In [2]: /zip (1,2,3),(4,5,6)
228 In [2]: /zip (1,2,3),(4,5,6)
217 ------> zip ((1,2,3),(4,5,6))
229 ------> zip ((1,2,3),(4,5,6))
218 Out[2]= [(1, 4), (2, 5), (3, 6)]
230 Out[2]= [(1, 4), (2, 5), (3, 6)]
219
231
220 IPython tells you that it has altered your command line by
232 IPython tells you that it has altered your command line by
221 displaying the new command line preceded by -->. e.g.:
233 displaying the new command line preceded by -->. e.g.::
234
222 In [18]: callable list
235 In [18]: callable list
223 -------> callable (list)
236 -------> callable (list)
224
237
225 2. Auto-Quoting
238 2. Auto-Quoting
239
226 You can force auto-quoting of a function's arguments by using ',' as
240 You can force auto-quoting of a function's arguments by using ',' as
227 the first character of a line. For example:
241 the first character of a line. For example::
242
228 In [1]: ,my_function /home/me # becomes my_function("/home/me")
243 In [1]: ,my_function /home/me # becomes my_function("/home/me")
229
244
230 If you use ';' instead, the whole argument is quoted as a single
245 If you use ';' instead, the whole argument is quoted as a single
231 string (while ',' splits on whitespace):
246 string (while ',' splits on whitespace)::
247
232 In [2]: ,my_function a b c # becomes my_function("a","b","c")
248 In [2]: ,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")
249 In [3]: ;my_function a b c # becomes my_function("a b c")
234
250
235 Note that the ',' MUST be the first character on the line! This
251 Note that the ',' MUST be the first character on the line! This
236 won't work:
252 won't work::
253
237 In [4]: x = ,my_function /home/me # syntax error
254 In [4]: x = ,my_function /home/me # syntax error
238 """
255 """
239
256
240 interactive_usage_min = """\
257 interactive_usage_min = """\
241 An enhanced console for Python.
258 An enhanced console for Python.
242 Some of its features are:
259 Some of its features are:
243 - Readline support if the readline library is present.
260 - Readline support if the readline library is present.
244 - Tab completion in the local namespace.
261 - Tab completion in the local namespace.
245 - Logging of input, see command-line options.
262 - Logging of input, see command-line options.
246 - System shell escape via ! , eg !ls.
263 - System shell escape via ! , eg !ls.
247 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
264 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
248 - Keeps track of locally defined variables via %who, %whos.
265 - Keeps track of locally defined variables via %who, %whos.
249 - Show object information with a ? eg ?x or x? (use ?? for more info).
266 - Show object information with a ? eg ?x or x? (use ?? for more info).
250 """
267 """
251
268
252 quick_reference = r"""
269 quick_reference = r"""
253 IPython -- An enhanced Interactive Python - Quick Reference Card
270 IPython -- An enhanced Interactive Python - Quick Reference Card
254 ================================================================
271 ================================================================
255
272
256 obj?, obj?? : Get help, or more help for object (also works as
273 obj?, obj?? : Get help, or more help for object (also works as
257 ?obj, ??obj).
274 ?obj, ??obj).
258 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
275 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
259 %magic : Information about IPython's 'magic' % functions.
276 %magic : Information about IPython's 'magic' % functions.
260
277
261 Magic functions are prefixed by % or %%, and typically take their arguments
278 Magic functions are prefixed by % or %%, and typically take their arguments
262 without parentheses, quotes or even commas for convenience. Line magics take a
279 without parentheses, quotes or even commas for convenience. Line magics take a
263 single % and cell magics are prefixed with two %%.
280 single % and cell magics are prefixed with two %%.
264
281
265 Example magic function calls:
282 Example magic function calls:
266
283
267 %alias d ls -F : 'd' is now an alias for 'ls -F'
284 %alias d ls -F : 'd' is now an alias for 'ls -F'
268 alias d ls -F : Works if 'alias' not a python name
285 alias d ls -F : Works if 'alias' not a python name
269 alist = %alias : Get list of aliases to 'alist'
286 alist = %alias : Get list of aliases to 'alist'
270 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
287 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
271 %cd?? : See help AND source for magic %cd
288 %cd?? : See help AND source for magic %cd
272 %timeit x=10 : time the 'x=10' statement with high precision.
289 %timeit x=10 : time the 'x=10' statement with high precision.
273 %%timeit x=2**100
290 %%timeit x=2**100
274 x**100 : time 'x*100' with a setup of 'x=2**100'; setup code is not
291 x**100 : time 'x*100' with a setup of 'x=2**100'; setup code is not
275 counted. This is an example of a cell magic.
292 counted. This is an example of a cell magic.
276
293
277 System commands:
294 System commands:
278
295
279 !cp a.txt b/ : System command escape, calls os.system()
296 !cp a.txt b/ : System command escape, calls os.system()
280 cp a.txt b/ : after %rehashx, most system commands work without !
297 cp a.txt b/ : after %rehashx, most system commands work without !
281 cp ${f}.txt $bar : Variable expansion in magics and system commands
298 cp ${f}.txt $bar : Variable expansion in magics and system commands
282 files = !ls /usr : Capture sytem command output
299 files = !ls /usr : Capture sytem command output
283 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
300 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
284
301
285 History:
302 History:
286
303
287 _i, _ii, _iii : Previous, next previous, next next previous input
304 _i, _ii, _iii : Previous, next previous, next next previous input
288 _i4, _ih[2:5] : Input history line 4, lines 2-4
305 _i4, _ih[2:5] : Input history line 4, lines 2-4
289 exec _i81 : Execute input history line #81 again
306 exec _i81 : Execute input history line #81 again
290 %rep 81 : Edit input history line #81
307 %rep 81 : Edit input history line #81
291 _, __, ___ : previous, next previous, next next previous output
308 _, __, ___ : previous, next previous, next next previous output
292 _dh : Directory history
309 _dh : Directory history
293 _oh : Output history
310 _oh : Output history
294 %hist : Command history. '%hist -g foo' search history for 'foo'
311 %hist : Command history. '%hist -g foo' search history for 'foo'
295
312
296 Autocall:
313 Autocall:
297
314
298 f 1,2 : f(1,2) # Off by default, enable with %autocall magic.
315 f 1,2 : f(1,2) # Off by default, enable with %autocall magic.
299 /f 1,2 : f(1,2) (forced autoparen)
316 /f 1,2 : f(1,2) (forced autoparen)
300 ,f 1 2 : f("1","2")
317 ,f 1 2 : f("1","2")
301 ;f 1 2 : f("1 2")
318 ;f 1 2 : f("1 2")
302
319
303 Remember: TAB completion works in many contexts, not just file names
320 Remember: TAB completion works in many contexts, not just file names
304 or python names.
321 or python names.
305
322
306 The following magic functions are currently available:
323 The following magic functions are currently available:
307
324
308 """
325 """
309
326
310 gui_reference = """\
327 gui_reference = """\
311 ===============================
328 ===============================
312 The graphical IPython console
329 The graphical IPython console
313 ===============================
330 ===============================
314
331
315 This console is designed to emulate the look, feel and workflow of a terminal
332 This console is designed to emulate the look, feel and workflow of a terminal
316 environment, while adding a number of enhancements that are simply not possible
333 environment, while adding a number of enhancements that are simply not possible
317 in a real terminal, such as inline syntax highlighting, true multiline editing,
334 in a real terminal, such as inline syntax highlighting, true multiline editing,
318 inline graphics and much more.
335 inline graphics and much more.
319
336
320 This quick reference document contains the basic information you'll need to
337 This quick reference document contains the basic information you'll need to
321 know to make the most efficient use of it. For the various command line
338 know to make the most efficient use of it. For the various command line
322 options available at startup, type ``ipython qtconsole --help`` at the command line.
339 options available at startup, type ``ipython qtconsole --help`` at the command line.
323
340
324
341
325 Multiline editing
342 Multiline editing
326 =================
343 =================
327
344
328 The graphical console is capable of true multiline editing, but it also tries
345 The graphical console is capable of true multiline editing, but it also tries
329 to behave intuitively like a terminal when possible. If you are used to
346 to behave intuitively like a terminal when possible. If you are used to
330 IPython's old terminal behavior, you should find the transition painless, and
347 IPython's old terminal behavior, you should find the transition painless, and
331 once you learn a few basic keybindings it will be a much more efficient
348 once you learn a few basic keybindings it will be a much more efficient
332 environment.
349 environment.
333
350
334 For single expressions or indented blocks, the console behaves almost like the
351 For single expressions or indented blocks, the console behaves almost like the
335 terminal IPython: single expressions are immediately evaluated, and indented
352 terminal IPython: single expressions are immediately evaluated, and indented
336 blocks are evaluated once a single blank line is entered::
353 blocks are evaluated once a single blank line is entered::
337
354
338 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
355 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
339 Hello IPython!
356 Hello IPython!
340
357
341 In [2]: for i in range(10):
358 In [2]: for i in range(10):
342 ...: print i,
359 ...: print i,
343 ...:
360 ...:
344 0 1 2 3 4 5 6 7 8 9
361 0 1 2 3 4 5 6 7 8 9
345
362
346 If you want to enter more than one expression in a single input block
363 If you want to enter more than one expression in a single input block
347 (something not possible in the terminal), you can use ``Control-Enter`` at the
364 (something not possible in the terminal), you can use ``Control-Enter`` at the
348 end of your first line instead of ``Enter``. At that point the console goes
365 end of your first line instead of ``Enter``. At that point the console goes
349 into 'cell mode' and even if your inputs are not indented, it will continue
366 into 'cell mode' and even if your inputs are not indented, it will continue
350 accepting arbitrarily many lines until either you enter an extra blank line or
367 accepting arbitrarily many lines until either you enter an extra blank line or
351 you hit ``Shift-Enter`` (the key binding that forces execution). When a
368 you hit ``Shift-Enter`` (the key binding that forces execution). When a
352 multiline cell is entered, IPython analyzes it and executes its code producing
369 multiline cell is entered, IPython analyzes it and executes its code producing
353 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
370 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
354 cell is executed as if it was a script. An example should clarify this::
371 cell is executed as if it was a script. An example should clarify this::
355
372
356 In [3]: x=1 # Hit C-Enter here
373 In [3]: x=1 # Hit C-Enter here
357 ...: y=2 # from now on, regular Enter is sufficient
374 ...: y=2 # from now on, regular Enter is sufficient
358 ...: z=3
375 ...: z=3
359 ...: x**2 # This does *not* produce an Out[] value
376 ...: x**2 # This does *not* produce an Out[] value
360 ...: x+y+z # Only the last expression does
377 ...: x+y+z # Only the last expression does
361 ...:
378 ...:
362 Out[3]: 6
379 Out[3]: 6
363
380
364 The behavior where an extra blank line forces execution is only active if you
381 The behavior where an extra blank line forces execution is only active if you
365 are actually typing at the keyboard each line, and is meant to make it mimic
382 are actually typing at the keyboard each line, and is meant to make it mimic
366 the IPython terminal behavior. If you paste a long chunk of input (for example
383 the IPython terminal behavior. If you paste a long chunk of input (for example
367 a long script copied form an editor or web browser), it can contain arbitrarily
384 a long script copied form an editor or web browser), it can contain arbitrarily
368 many intermediate blank lines and they won't cause any problems. As always,
385 many intermediate blank lines and they won't cause any problems. As always,
369 you can then make it execute by appending a blank line *at the end* or hitting
386 you can then make it execute by appending a blank line *at the end* or hitting
370 ``Shift-Enter`` anywhere within the cell.
387 ``Shift-Enter`` anywhere within the cell.
371
388
372 With the up arrow key, you can retrieve previous blocks of input that contain
389 With the up arrow key, you can retrieve previous blocks of input that contain
373 multiple lines. You can move inside of a multiline cell like you would in any
390 multiple lines. You can move inside of a multiline cell like you would in any
374 text editor. When you want it executed, the simplest thing to do is to hit the
391 text editor. When you want it executed, the simplest thing to do is to hit the
375 force execution key, ``Shift-Enter`` (though you can also navigate to the end
392 force execution key, ``Shift-Enter`` (though you can also navigate to the end
376 and append a blank line by using ``Enter`` twice).
393 and append a blank line by using ``Enter`` twice).
377
394
378 If you've edited a multiline cell and accidentally navigate out of it with the
395 If you've edited a multiline cell and accidentally navigate out of it with the
379 up or down arrow keys, IPython will clear the cell and replace it with the
396 up or down arrow keys, IPython will clear the cell and replace it with the
380 contents of the one above or below that you navigated to. If this was an
397 contents of the one above or below that you navigated to. If this was an
381 accident and you want to retrieve the cell you were editing, use the Undo
398 accident and you want to retrieve the cell you were editing, use the Undo
382 keybinding, ``Control-z``.
399 keybinding, ``Control-z``.
383
400
384
401
385 Key bindings
402 Key bindings
386 ============
403 ============
387
404
388 The IPython console supports most of the basic Emacs line-oriented keybindings,
405 The IPython console supports most of the basic Emacs line-oriented keybindings,
389 in addition to some of its own.
406 in addition to some of its own.
390
407
391 The keybinding prefixes mean:
408 The keybinding prefixes mean:
392
409
393 - ``C``: Control
410 - ``C``: Control
394 - ``S``: Shift
411 - ``S``: Shift
395 - ``M``: Meta (typically the Alt key)
412 - ``M``: Meta (typically the Alt key)
396
413
397 The keybindings themselves are:
414 The keybindings themselves are:
398
415
399 - ``Enter``: insert new line (may cause execution, see above).
416 - ``Enter``: insert new line (may cause execution, see above).
400 - ``C-Enter``: *force* new line, *never* causes execution.
417 - ``C-Enter``: *force* new line, *never* causes execution.
401 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
418 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
402 - ``Up``: step backwards through the history.
419 - ``Up``: step backwards through the history.
403 - ``Down``: step forwards through the history.
420 - ``Down``: step forwards through the history.
404 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
421 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
405 - ``S-Down``: search forwards through the history.
422 - ``S-Down``: search forwards through the history.
406 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
423 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
407 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
424 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
408 - ``C-v``: paste text from clipboard.
425 - ``C-v``: paste text from clipboard.
409 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
426 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
410 - ``C-S-z``: redo.
427 - ``C-S-z``: redo.
411 - ``C-o``: move to 'other' area, between pager and terminal.
428 - ``C-o``: move to 'other' area, between pager and terminal.
412 - ``C-l``: clear terminal.
429 - ``C-l``: clear terminal.
413 - ``C-a``: go to beginning of line.
430 - ``C-a``: go to beginning of line.
414 - ``C-e``: go to end of line.
431 - ``C-e``: go to end of line.
415 - ``C-u``: kill from cursor to the begining of the line.
432 - ``C-u``: kill from cursor to the begining of the line.
416 - ``C-k``: kill from cursor to the end of the line.
433 - ``C-k``: kill from cursor to the end of the line.
417 - ``C-y``: yank (paste)
434 - ``C-y``: yank (paste)
418 - ``C-p``: previous line (like up arrow)
435 - ``C-p``: previous line (like up arrow)
419 - ``C-n``: next line (like down arrow)
436 - ``C-n``: next line (like down arrow)
420 - ``C-f``: forward (like right arrow)
437 - ``C-f``: forward (like right arrow)
421 - ``C-b``: back (like left arrow)
438 - ``C-b``: back (like left arrow)
422 - ``C-d``: delete next character, or exits if input is empty
439 - ``C-d``: delete next character, or exits if input is empty
423 - ``M-<``: move to the beginning of the input region.
440 - ``M-<``: move to the beginning of the input region.
424 - ``M->``: move to the end of the input region.
441 - ``M->``: move to the end of the input region.
425 - ``M-d``: delete next word.
442 - ``M-d``: delete next word.
426 - ``M-Backspace``: delete previous word.
443 - ``M-Backspace``: delete previous word.
427 - ``C-.``: force a kernel restart (a confirmation dialog appears).
444 - ``C-.``: force a kernel restart (a confirmation dialog appears).
428 - ``C-+``: increase font size.
445 - ``C-+``: increase font size.
429 - ``C--``: decrease font size.
446 - ``C--``: decrease font size.
430 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
447 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
431
448
432 The IPython pager
449 The IPython pager
433 =================
450 =================
434
451
435 IPython will show long blocks of text from many sources using a builtin pager.
452 IPython will show long blocks of text from many sources using a builtin pager.
436 You can control where this pager appears with the ``--paging`` command-line
453 You can control where this pager appears with the ``--paging`` command-line
437 flag:
454 flag:
438
455
439 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
456 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
440 must quit the pager to get back to the terminal (similar to how a pager such
457 must quit the pager to get back to the terminal (similar to how a pager such
441 as ``less`` or ``more`` works).
458 as ``less`` or ``more`` works).
442
459
443 - ``vsplit``: the console is made double-tall, and the pager appears on the
460 - ``vsplit``: the console is made double-tall, and the pager appears on the
444 bottom area when needed. You can view its contents while using the terminal.
461 bottom area when needed. You can view its contents while using the terminal.
445
462
446 - ``hsplit``: the console is made double-wide, and the pager appears on the
463 - ``hsplit``: the console is made double-wide, and the pager appears on the
447 right area when needed. You can view its contents while using the terminal.
464 right area when needed. You can view its contents while using the terminal.
448
465
449 - ``none``: the console never pages output.
466 - ``none``: the console never pages output.
450
467
451 If you use the vertical or horizontal paging modes, you can navigate between
468 If you use the vertical or horizontal paging modes, you can navigate between
452 terminal and pager as follows:
469 terminal and pager as follows:
453
470
454 - Tab key: goes from pager to terminal (but not the other way around).
471 - Tab key: goes from pager to terminal (but not the other way around).
455 - Control-o: goes from one to another always.
472 - Control-o: goes from one to another always.
456 - Mouse: click on either.
473 - Mouse: click on either.
457
474
458 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
475 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
459 focus on the pager area).
476 focus on the pager area).
460
477
461 Running subprocesses
478 Running subprocesses
462 ====================
479 ====================
463
480
464 The graphical IPython console uses the ``pexpect`` module to run subprocesses
481 The graphical IPython console uses the ``pexpect`` module to run subprocesses
465 when you type ``!command``. This has a number of advantages (true asynchronous
482 when you type ``!command``. This has a number of advantages (true asynchronous
466 output from subprocesses as well as very robust termination of rogue
483 output from subprocesses as well as very robust termination of rogue
467 subprocesses with ``Control-C``), as well as some limitations. The main
484 subprocesses with ``Control-C``), as well as some limitations. The main
468 limitation is that you can *not* interact back with the subprocess, so anything
485 limitation is that you can *not* interact back with the subprocess, so anything
469 that invokes a pager or expects you to type input into it will block and hang
486 that invokes a pager or expects you to type input into it will block and hang
470 (you can kill it with ``Control-C``).
487 (you can kill it with ``Control-C``).
471
488
472 We have provided as magics ``%less`` to page files (aliased to ``%more``),
489 We have provided as magics ``%less`` to page files (aliased to ``%more``),
473 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
490 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
474 most common commands you'd want to call in your subshell and that would cause
491 most common commands you'd want to call in your subshell and that would cause
475 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
492 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
476
493
477 Display
494 Display
478 =======
495 =======
479
496
480 The IPython console can now display objects in a variety of formats, including
497 The IPython console can now display objects in a variety of formats, including
481 HTML, PNG and SVG. This is accomplished using the display functions in
498 HTML, PNG and SVG. This is accomplished using the display functions in
482 ``IPython.core.display``::
499 ``IPython.core.display``::
483
500
484 In [4]: from IPython.core.display import display, display_html
501 In [4]: from IPython.core.display import display, display_html
485
502
486 In [5]: from IPython.core.display import display_png, display_svg
503 In [5]: from IPython.core.display import display_png, display_svg
487
504
488 Python objects can simply be passed to these functions and the appropriate
505 Python objects can simply be passed to these functions and the appropriate
489 representations will be displayed in the console as long as the objects know
506 representations will be displayed in the console as long as the objects know
490 how to compute those representations. The easiest way of teaching objects how
507 how to compute those representations. The easiest way of teaching objects how
491 to format themselves in various representations is to define special methods
508 to format themselves in various representations is to define special methods
492 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
509 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
493 can also be given custom formatter functions for various types::
510 can also be given custom formatter functions for various types::
494
511
495 In [6]: ip = get_ipython()
512 In [6]: ip = get_ipython()
496
513
497 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
514 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
498
515
499 In [8]: html_formatter.for_type(Foo, foo_to_html)
516 In [8]: html_formatter.for_type(Foo, foo_to_html)
500
517
501 For further details, see ``IPython.core.formatters``.
518 For further details, see ``IPython.core.formatters``.
502
519
503 Inline matplotlib graphics
520 Inline matplotlib graphics
504 ==========================
521 ==========================
505
522
506 The IPython console is capable of displaying matplotlib figures inline, in SVG
523 The IPython console is capable of displaying matplotlib figures inline, in SVG
507 or PNG format. If started with the ``pylab=inline``, then all figures are
524 or PNG format. If started with the ``pylab=inline``, then all figures are
508 rendered inline automatically (PNG by default). If started with ``--pylab``
525 rendered inline automatically (PNG by default). If started with ``--pylab``
509 or ``pylab=<your backend>``, then a GUI backend will be used, but IPython's
526 or ``pylab=<your backend>``, then a GUI backend will be used, but IPython's
510 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
527 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
511
528
512 In [9]: display(*getfigs()) # display all figures inline
529 In [9]: display(*getfigs()) # display all figures inline
513
530
514 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
531 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
515 """
532 """
516
533
517
534
518 quick_guide = """\
535 quick_guide = """\
519 ? -> Introduction and overview of IPython's features.
536 ? -> Introduction and overview of IPython's features.
520 %quickref -> Quick reference.
537 %quickref -> Quick reference.
521 help -> Python's own help system.
538 help -> Python's own help system.
522 object? -> Details about 'object', use 'object??' for extra details.
539 object? -> Details about 'object', use 'object??' for extra details.
523 """
540 """
524
541
525 gui_note = """\
542 gui_note = """\
526 %guiref -> A brief reference about the graphical user interface.
543 %guiref -> A brief reference about the graphical user interface.
527 """
544 """
528
545
529 default_banner_parts = [
546 default_banner_parts = [
530 'Python %s\n' % (sys.version.split('\n')[0],),
547 'Python %s\n' % (sys.version.split('\n')[0],),
531 'Type "copyright", "credits" or "license" for more information.\n\n',
548 'Type "copyright", "credits" or "license" for more information.\n\n',
532 'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
549 'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
533 quick_guide
550 quick_guide
534 ]
551 ]
535
552
536 default_gui_banner_parts = default_banner_parts + [gui_note]
553 default_gui_banner_parts = default_banner_parts + [gui_note]
537
554
538 default_banner = ''.join(default_banner_parts)
555 default_banner = ''.join(default_banner_parts)
539
556
540 default_gui_banner = ''.join(default_gui_banner_parts)
557 default_gui_banner = ''.join(default_gui_banner_parts)
541
558
542 # page GUI Reference, for use as a magic:
559 # page GUI Reference, for use as a magic:
543
560
544 def page_guiref(arg_s=None):
561 def page_guiref(arg_s=None):
545 """Show a basic reference about the GUI Console."""
562 """Show a basic reference about the GUI Console."""
546 from IPython.core import page
563 from IPython.core import page
547 page.page(gui_reference, auto_html=True)
564 page.page(gui_reference, auto_html=True)
548
565
General Comments 0
You need to be logged in to leave comments. Login now