Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 573 lines (424 sloc) 23.364 kb
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
1 # -*- coding: utf-8 -*-
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
2 """Usage information for the main IPython applications.
3 """
4 #-----------------------------------------------------------------------------
c82649e @Carreau update copyright to 2011/20xx-2011
Carreau authored
5 # Copyright (C) 2008-2011 The IPython Development Team
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
7 #
8 # Distributed under the terms of the BSD License. The full license is in
9 # the file COPYING, distributed as part of this software.
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
10 #-----------------------------------------------------------------------------
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
11
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
12 import sys
13 from IPython.core import release
14
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
15 cl_usage = """\
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
16 =========
17 IPython
18 =========
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
19
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
20 Tools for Interactive Computing in Python
21 =========================================
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
22
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
23 A Python shell with automatic history (input and output), dynamic object
24 introspection, easier configuration, command completion, access to the
25 system shell and more. IPython can also be embedded in running programs.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
26
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
27
28 Usage
29
c8a24c1 @minrk mention `--` in usage
minrk authored
30 ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ...
41eaa28 @minrk fix ipython usage text
minrk authored
31
32 If invoked with no options, it executes the file and exits, passing the
33 remaining arguments to the script, just as if you had specified the same
c8a24c1 @minrk mention `--` in usage
minrk authored
34 command with python. You may need to specify `--` before args to be passed
35 to the script, to prevent IPython from attempting to parse them. If you
36 specify the option `-i` before the filename, it will enter an interactive
37 IPython session after running the script, rather than exiting. Files ending
38 in .py will be treated as normal Python, but files ending in .ipy can
39 contain special IPython syntax (magic commands, shell expansions, etc.).
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
40
d666717 @minrk update usage.py for 0.11
minrk authored
41 Almost all configuration in IPython is available via the command-line. Do
42 `ipython --help-all` to see all available options. For persistent
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
43 configuration, look into your `ipython_config.py` configuration file for
d666717 @minrk update usage.py for 0.11
minrk authored
44 details.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
45
803d13d @bfroehle IPYTHON_DIR -> IPYTHONDIR in comments and documentation
bfroehle authored
46 This file is typically installed in the `IPYTHONDIR` directory, and there
d666717 @minrk update usage.py for 0.11
minrk authored
47 is a separate configuration directory for each profile. The default profile
c6bbf96 @ivanov a couple of more stray XDG / .config references
ivanov authored
48 directory will be located in $IPYTHONDIR/profile_default. IPYTHONDIR
49 defaults to to `$HOME/.ipython`. For Windows users, $HOME resolves to
cf9c39f @adalq Updated Windows HOME folder
adalq authored
50 C:\\Users\\YourUserName in most instances.
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
51
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
52 To initialize a profile with the default configuration file, do::
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
53
d666717 @minrk update usage.py for 0.11
minrk authored
54 $> ipython profile create
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
55
803d13d @bfroehle IPYTHON_DIR -> IPYTHONDIR in comments and documentation
bfroehle authored
56 and start editing `IPYTHONDIR/profile_default/ipython_config.py`
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
57
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
58 In IPython's documentation, we will refer to this directory as
803d13d @bfroehle IPYTHON_DIR -> IPYTHONDIR in comments and documentation
bfroehle authored
59 `IPYTHONDIR`, you can change its default location by creating an
4037037 @fperez Fix padding of matplotlib figures, after much whining from Stefan :)
fperez authored
60 environment variable with this name and setting it to the desired path.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
61
d81b8d5 @fperez Unify command-line usage information in one place.
fperez authored
62 For more information, see the manual available in HTML and PDF in your
971c163 @takluyver Update various references to IPython's homepage.
takluyver authored
63 installation, or online at http://ipython.org/documentation.html.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
64 """
65
66 interactive_usage = """
67 IPython -- An enhanced Interactive Python
68 =========================================
69
70 IPython offers a combination of convenient shell features, special commands
71 and a history mechanism for both input (command history) and output (results
72 caching, similar to Mathematica). It is intended to be a fully compatible
73 replacement for the standard Python interpreter, while offering vastly
74 improved functionality and flexibility.
75
d666717 @minrk update usage.py for 0.11
minrk authored
76 At your system command line, type 'ipython -h' to see the command line
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
77 options available. This document only describes interactive features.
78
79 MAIN FEATURES
c139a83 @ccordoba12 Make interactive_usage a bit more rst friendly
ccordoba12 authored
80 -------------
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
81
82 * Access to the standard Python help. As of Python 2.1, a help system is
83 available with access to object docstrings and the Python manuals. Simply
84 type 'help' (no quotes) to access it.
85
86 * Magic commands: type %magic for information on the magic subsystem.
87
f74f429 @eteq purged ipythonrc from documentation and docstrings where no longer relev...
eteq authored
88 * System command aliases, via the %alias command or the configuration file(s).
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
89
90 * Dynamic object information:
91
92 Typing ?word or word? prints detailed information about an object. If
93 certain strings in the object are too long (docstrings, code, etc.) they get
94 snipped in the center for brevity.
95
96 Typing ??word or word?? gives access to the full information without
97 snipping long strings. Long strings are sent to the screen through the less
98 pager if longer than the screen, printed otherwise.
99
100 The ?/?? system gives access to the full source code for any object (if
101 available), shows function prototypes and other useful information.
102
103 If you just want to see an object's docstring, type '%pdoc object' (without
104 quotes, and without % if you have automagic on).
105
106 * Completion in the local namespace, by typing TAB at the prompt.
107
108 At any time, hitting tab will complete any available python commands or
109 variable names, and show you a list of the possible completions if there's
110 no unambiguous one. It will also complete filenames in the current directory.
111
112 This feature requires the readline and rlcomplete modules, so it won't work
113 if your Python lacks readline support (such as under Windows).
114
115 * Search previous command history in two ways (also requires readline):
116
117 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
c139a83 @ccordoba12 Make interactive_usage a bit more rst friendly
ccordoba12 authored
118 search through only the history items that match what you've typed so
119 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
120 normal arrow keys.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
121
122 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
c139a83 @ccordoba12 Make interactive_usage a bit more rst friendly
ccordoba12 authored
123 your history for lines that match what you've typed so far, completing as
124 much as it can.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
125
d666717 @minrk update usage.py for 0.11
minrk authored
126 - %hist: search history by index (this does *not* require readline).
127
128 * Persistent command history across sessions.
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
129
130 * Logging of input with the ability to save and restore a working session.
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
131
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
132 * System escape with !. Typing !ls will run 'ls' in the current directory.
133
134 * The reload command does a 'deep' reload of a module: changes made to the
135 module since you imported will actually be available without having to exit.
136
137 * Verbose and colored exception traceback printouts. See the magic xmode and
138 xcolor functions for details (just type %magic).
139
140 * Input caching system:
141
142 IPython offers numbered prompts (In/Out) with input and output caching. All
143 input is saved and can be retrieved as variables (besides the usual arrow
144 key recall).
145
146 The following GLOBAL variables always exist (so don't overwrite them!):
147 _i: stores previous input.
148 _ii: next previous.
149 _iii: next-next previous.
150 _ih : a list of all input _ih[n] is the input from line n.
151
152 Additionally, global variables named _i<n> are dynamically created (<n>
153 being the prompt counter), such that _i<n> == _ih[<n>]
154
155 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
156
157 You can create macros which contain multiple input lines from this history,
158 for later re-execution, with the %macro function.
159
160 The history function %hist allows you to see any part of your input history
161 by printing a range of the _i variables. Note that inputs which contain
162 magic functions (%) appear in the history with a prepended comment. This is
163 because they aren't really valid Python code, so you can't exec them.
164
165 * Output caching system:
166
167 For output that is returned from actions, a system similar to the input
168 cache exists but using _ instead of _i. Only actions that produce a result
169 (NOT assignments, for example) are cached. If you are familiar with
170 Mathematica, IPython's _ variables behave exactly like Mathematica's %
171 variables.
172
173 The following GLOBAL variables always exist (so don't overwrite them!):
174 _ (one underscore): previous output.
175 __ (two underscores): next previous.
176 ___ (three underscores): next-next previous.
177
178 Global variables named _<n> are dynamically created (<n> being the prompt
179 counter), such that the result of output <n> is always available as _<n>.
180
181 Finally, a global dictionary named _oh exists with entries for all lines
182 which generated output.
183
184 * Directory history:
185
186 Your history of visited directories is kept in the global list _dh, and the
187 magic %cd command can be used to go to any entry in that list.
188
189 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
190
c139a83 @ccordoba12 Make interactive_usage a bit more rst friendly
ccordoba12 authored
191 1. Auto-parentheses
192
193 Callable objects (i.e. functions, methods, etc) can be invoked like
194 this (notice the commas between the arguments)::
195
196 In [1]: callable_ob arg1, arg2, arg3
197
198 and the input will be translated to this::
199
200 callable_ob(arg1, arg2, arg3)
201
202 This feature is off by default (in rare cases it can produce
203 undesirable side-effects), but you can activate it at the command-line
204 by starting IPython with `--autocall 1`, set it permanently in your
205 configuration file, or turn on at runtime with `%autocall 1`.
206
207 You can force auto-parentheses by using '/' as the first character
208 of a line. For example::
209
210 In [1]: /globals # becomes 'globals()'
211
212 Note that the '/' MUST be the first character on the line! This
213 won't work::
214
215 In [2]: print /globals # syntax error
216
217 In most cases the automatic algorithm should work, so you should
218 rarely need to explicitly invoke /. One notable exception is if you
219 are trying to call a function with a list of tuples as arguments (the
220 parenthesis will confuse IPython)::
221
222 In [1]: zip (1,2,3),(4,5,6) # won't work
223
224 but this will work::
225
226 In [2]: /zip (1,2,3),(4,5,6)
227 ------> zip ((1,2,3),(4,5,6))
228 Out[2]= [(1, 4), (2, 5), (3, 6)]
229
230 IPython tells you that it has altered your command line by
231 displaying the new command line preceded by -->. e.g.::
232
233 In [18]: callable list
234 -------> callable (list)
235
236 2. Auto-Quoting
237
238 You can force auto-quoting of a function's arguments by using ',' as
239 the first character of a line. For example::
240
241 In [1]: ,my_function /home/me # becomes my_function("/home/me")
242
243 If you use ';' instead, the whole argument is quoted as a single
244 string (while ',' splits on whitespace)::
245
246 In [2]: ,my_function a b c # becomes my_function("a","b","c")
247 In [3]: ;my_function a b c # becomes my_function("a b c")
248
249 Note that the ',' MUST be the first character on the line! This
250 won't work::
251
252 In [4]: x = ,my_function /home/me # syntax error
6f629fc Reorganized the directory for ipython/ to have its own dir, which is a b...
fperez authored
253 """
73c8422 %quickref
vivainio authored
254
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
255 interactive_usage_min = """\
256 An enhanced console for Python.
257 Some of its features are:
258 - Readline support if the readline library is present.
259 - Tab completion in the local namespace.
260 - Logging of input, see command-line options.
261 - System shell escape via ! , eg !ls.
262 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
263 - Keeps track of locally defined variables via %who, %whos.
264 - Show object information with a ? eg ?x or x? (use ?? for more info).
265 """
266
73c8422 %quickref
vivainio authored
267 quick_reference = r"""
268 IPython -- An enhanced Interactive Python - Quick Reference Card
269 ================================================================
270
a1312bc - Fixes for doctest support. Need more testing, esp. to be sure they do...
fperez authored
271 obj?, obj?? : Get help, or more help for object (also works as
272 ?obj, ??obj).
273 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
274 %magic : Information about IPython's 'magic' % functions.
73c8422 %quickref
vivainio authored
275
16171ea @fperez Update interactive usage message (used by %quickref and others).
fperez authored
276 Magic functions are prefixed by % or %%, and typically take their arguments
277 without parentheses, quotes or even commas for convenience. Line magics take a
278 single % and cell magics are prefixed with two %%.
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
279
5b2e581 Change banner, %quickref
vivainio authored
280 Example magic function calls:
281
73c8422 %quickref
vivainio authored
282 %alias d ls -F : 'd' is now an alias for 'ls -F'
283 alias d ls -F : Works if 'alias' not a python name
284 alist = %alias : Get list of aliases to 'alist'
5b2e581 Change banner, %quickref
vivainio authored
285 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
286 %cd?? : See help AND source for magic %cd
16171ea @fperez Update interactive usage message (used by %quickref and others).
fperez authored
287 %timeit x=10 : time the 'x=10' statement with high precision.
288 %%timeit x=2**100
4dad074 @jonasc Fix description which did not match the code
jonasc authored
289 x**100 : time 'x**100' with a setup of 'x=2**100'; setup code is not
16171ea @fperez Update interactive usage message (used by %quickref and others).
fperez authored
290 counted. This is an example of a cell magic.
73c8422 %quickref
vivainio authored
291
292 System commands:
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
293
73c8422 %quickref
vivainio authored
294 !cp a.txt b/ : System command escape, calls os.system()
39e1b71 corrected some quickref glitches
vivainio authored
295 cp a.txt b/ : after %rehashx, most system commands work without !
73c8422 %quickref
vivainio authored
296 cp ${f}.txt $bar : Variable expansion in magics and system commands
39e1b71 corrected some quickref glitches
vivainio authored
297 files = !ls /usr : Capture sytem command output
73c8422 %quickref
vivainio authored
298 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
299
300 History:
301
302 _i, _ii, _iii : Previous, next previous, next next previous input
b114b8c merge all from 0.7.3 branch to trunk
vivainio authored
303 _i4, _ih[2:5] : Input history line 4, lines 2-4
304 exec _i81 : Execute input history line #81 again
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
305 %rep 81 : Edit input history line #81
73c8422 %quickref
vivainio authored
306 _, __, ___ : previous, next previous, next next previous output
307 _dh : Directory history
308 _oh : Output history
2c54959 @nnathan provided more history examples in quick reference
nnathan authored
309 %hist : Command history of current session.
310 %hist -g foo : Search command history of (almost) all sessions for 'foo'.
311 %hist -g : Command history of (almost) all sessions.
312 %hist 1/2-8 : Command history containing lines 2-8 of session 1.
313 %hist 1/ ~2/ : Command history of session 1 and 2 sessions before current.
314 %hist ~8/1-~6/5 : Command history from line 1 of 8 sessions ago to
315 line 5 of 6 sessions ago.
316 %edit 0/ : Open editor to execute code with history of current session.
73c8422 %quickref
vivainio authored
317
318 Autocall:
319
4643b61 @fperez Update docs about autocall and remove manual copy of cmd-line flags.
fperez authored
320 f 1,2 : f(1,2) # Off by default, enable with %autocall magic.
39e1b71 corrected some quickref glitches
vivainio authored
321 /f 1,2 : f(1,2) (forced autoparen)
73c8422 %quickref
vivainio authored
322 ,f 1 2 : f("1","2")
323 ;f 1 2 : f("1 2")
324
5b2e581 Change banner, %quickref
vivainio authored
325 Remember: TAB completion works in many contexts, not just file names
326 or python names.
327
328 The following magic functions are currently available:
329
73c8422 %quickref
vivainio authored
330 """
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
331
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
332 gui_reference = """\
333 ===============================
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
334 The graphical IPython console
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
335 ===============================
336
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
337 This console is designed to emulate the look, feel and workflow of a terminal
338 environment, while adding a number of enhancements that are simply not possible
339 in a real terminal, such as inline syntax highlighting, true multiline editing,
340 inline graphics and much more.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
341
342 This quick reference document contains the basic information you'll need to
343 know to make the most efficient use of it. For the various command line
d666717 @minrk update usage.py for 0.11
minrk authored
344 options available at startup, type ``ipython qtconsole --help`` at the command line.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
345
346
347 Multiline editing
348 =================
349
350 The graphical console is capable of true multiline editing, but it also tries
351 to behave intuitively like a terminal when possible. If you are used to
fc389ac Fix pyhton -> python typos (everywhere found by grep).
W. Trevor King authored
352 IPython's old terminal behavior, you should find the transition painless, and
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
353 once you learn a few basic keybindings it will be a much more efficient
354 environment.
355
356 For single expressions or indented blocks, the console behaves almost like the
b53578c @epatters Pressing Enter now always executes when the input buffer has one line.
epatters authored
357 terminal IPython: single expressions are immediately evaluated, and indented
358 blocks are evaluated once a single blank line is entered::
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
359
360 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
361 Hello IPython!
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
362
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
363 In [2]: for i in range(10):
364 ...: print i,
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
365 ...:
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
366 0 1 2 3 4 5 6 7 8 9
367
368 If you want to enter more than one expression in a single input block
369 (something not possible in the terminal), you can use ``Control-Enter`` at the
370 end of your first line instead of ``Enter``. At that point the console goes
371 into 'cell mode' and even if your inputs are not indented, it will continue
372 accepting arbitrarily many lines until either you enter an extra blank line or
373 you hit ``Shift-Enter`` (the key binding that forces execution). When a
374 multiline cell is entered, IPython analyzes it and executes its code producing
375 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
376 cell is executed as if it was a script. An example should clarify this::
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
377
378 In [3]: x=1 # Hit C-Enter here
379 ...: y=2 # from now on, regular Enter is sufficient
380 ...: z=3
381 ...: x**2 # This does *not* produce an Out[] value
382 ...: x+y+z # Only the last expression does
34c1043 @bernardofire remove all trailling spaces
bernardofire authored
383 ...:
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
384 Out[3]: 6
385
386 The behavior where an extra blank line forces execution is only active if you
387 are actually typing at the keyboard each line, and is meant to make it mimic
388 the IPython terminal behavior. If you paste a long chunk of input (for example
389 a long script copied form an editor or web browser), it can contain arbitrarily
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
390 many intermediate blank lines and they won't cause any problems. As always,
391 you can then make it execute by appending a blank line *at the end* or hitting
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
392 ``Shift-Enter`` anywhere within the cell.
393
394 With the up arrow key, you can retrieve previous blocks of input that contain
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
395 multiple lines. You can move inside of a multiline cell like you would in any
396 text editor. When you want it executed, the simplest thing to do is to hit the
397 force execution key, ``Shift-Enter`` (though you can also navigate to the end
398 and append a blank line by using ``Enter`` twice).
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
399
400 If you've edited a multiline cell and accidentally navigate out of it with the
401 up or down arrow keys, IPython will clear the cell and replace it with the
402 contents of the one above or below that you navigated to. If this was an
403 accident and you want to retrieve the cell you were editing, use the Undo
404 keybinding, ``Control-z``.
405
406
407 Key bindings
408 ============
409
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
410 The IPython console supports most of the basic Emacs line-oriented keybindings,
411 in addition to some of its own.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
412
413 The keybinding prefixes mean:
414
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
415 - ``C``: Control
416 - ``S``: Shift
417 - ``M``: Meta (typically the Alt key)
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
418
419 The keybindings themselves are:
420
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
421 - ``Enter``: insert new line (may cause execution, see above).
b63d2de @epatters Update %guiref with a note about Ctrl-R style history searching.
epatters authored
422 - ``C-Enter``: *force* new line, *never* causes execution.
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
423 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
b63d2de @epatters Update %guiref with a note about Ctrl-R style history searching.
epatters authored
424 - ``Up``: step backwards through the history.
425 - ``Down``: step forwards through the history.
426 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
427 - ``S-Down``: search forwards through the history.
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
428 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
429 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
430 - ``C-v``: paste text from clipboard.
431 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
432 - ``C-S-z``: redo.
433 - ``C-o``: move to 'other' area, between pager and terminal.
434 - ``C-l``: clear terminal.
435 - ``C-a``: go to beginning of line.
436 - ``C-e``: go to end of line.
0c2e430 @ivanov make Ctrl-D in qtconsole act same as in terminal
ivanov authored
437 - ``C-u``: kill from cursor to the begining of the line.
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
438 - ``C-k``: kill from cursor to the end of the line.
439 - ``C-y``: yank (paste)
440 - ``C-p``: previous line (like up arrow)
441 - ``C-n``: next line (like down arrow)
442 - ``C-f``: forward (like right arrow)
443 - ``C-b``: back (like left arrow)
0c2e430 @ivanov make Ctrl-D in qtconsole act same as in terminal
ivanov authored
444 - ``C-d``: delete next character, or exits if input is empty
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
445 - ``M-<``: move to the beginning of the input region.
446 - ``M->``: move to the end of the input region.
447 - ``M-d``: delete next word.
448 - ``M-Backspace``: delete previous word.
449 - ``C-.``: force a kernel restart (a confirmation dialog appears).
f0980fb @fperez Add Ctrl-+/- to increase/decrease font size.
fperez authored
450 - ``C-+``: increase font size.
451 - ``C--``: decrease font size.
677c8ce @Carreau add fullscreen support for QtConsole throught shortcut
Carreau authored
452 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
453
454 The IPython pager
455 =================
456
457 IPython will show long blocks of text from many sources using a builtin pager.
458 You can control where this pager appears with the ``--paging`` command-line
459 flag:
460
2c9c2c6 @epatters Update guiref with correct paging options.
epatters authored
461 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
462 must quit the pager to get back to the terminal (similar to how a pager such
463 as ``less`` or ``more`` works).
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
464
2c9c2c6 @epatters Update guiref with correct paging options.
epatters authored
465 - ``vsplit``: the console is made double-tall, and the pager appears on the
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
466 bottom area when needed. You can view its contents while using the terminal.
467
2c9c2c6 @epatters Update guiref with correct paging options.
epatters authored
468 - ``hsplit``: the console is made double-wide, and the pager appears on the
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
469 right area when needed. You can view its contents while using the terminal.
470
2c9c2c6 @epatters Update guiref with correct paging options.
epatters authored
471 - ``none``: the console never pages output.
472
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
473 If you use the vertical or horizontal paging modes, you can navigate between
474 terminal and pager as follows:
475
476 - Tab key: goes from pager to terminal (but not the other way around).
477 - Control-o: goes from one to another always.
478 - Mouse: click on either.
479
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
480 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
481 focus on the pager area).
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
482
483 Running subprocesses
484 ====================
485
486 The graphical IPython console uses the ``pexpect`` module to run subprocesses
487 when you type ``!command``. This has a number of advantages (true asynchronous
488 output from subprocesses as well as very robust termination of rogue
0a6b5a4 @fperez Fixes to guiref after more careful proofreading.
fperez authored
489 subprocesses with ``Control-C``), as well as some limitations. The main
490 limitation is that you can *not* interact back with the subprocess, so anything
491 that invokes a pager or expects you to type input into it will block and hang
492 (you can kill it with ``Control-C``).
493
494 We have provided as magics ``%less`` to page files (aliased to ``%more``),
495 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
496 most common commands you'd want to call in your subshell and that would cause
497 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
498
9716062 @ellisonbg Final work on display system.
ellisonbg authored
499 Display
500 =======
501
502 The IPython console can now display objects in a variety of formats, including
503 HTML, PNG and SVG. This is accomplished using the display functions in
504 ``IPython.core.display``::
505
506 In [4]: from IPython.core.display import display, display_html
507
508 In [5]: from IPython.core.display import display_png, display_svg
509
510 Python objects can simply be passed to these functions and the appropriate
511 representations will be displayed in the console as long as the objects know
512 how to compute those representations. The easiest way of teaching objects how
513 to format themselves in various representations is to define special methods
43a27cb @ellisonbg Renaming the special methods of the formatters.
ellisonbg authored
514 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
9716062 @ellisonbg Final work on display system.
ellisonbg authored
515 can also be given custom formatter functions for various types::
516
517 In [6]: ip = get_ipython()
518
519 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
520
521 In [8]: html_formatter.for_type(Foo, foo_to_html)
522
523 For further details, see ``IPython.core.formatters``.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
524
525 Inline matplotlib graphics
526 ==========================
527
528 The IPython console is capable of displaying matplotlib figures inline, in SVG
d5afa0b @Carreau pylab-> matplotlib
Carreau authored
529 or PNG format. If started with the ``matplotlib=inline``, then all figures are
530 rendered inline automatically (PNG by default). If started with ``--matplotlib``
531 or ``matplotlib=<your backend>``, then a GUI backend will be used, but IPython's
d666717 @minrk update usage.py for 0.11
minrk authored
532 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
9716062 @ellisonbg Final work on display system.
ellisonbg authored
533
534 In [9]: display(*getfigs()) # display all figures inline
535
536 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
537 """
538
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
539
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
540 quick_guide = """\
541 ? -> Introduction and overview of IPython's features.
542 %quickref -> Quick reference.
543 help -> Python's own help system.
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
544 object? -> Details about 'object', use 'object??' for extra details.
545 """
546
547 gui_note = """\
548 %guiref -> A brief reference about the graphical user interface.
549 """
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
550
1a8ed8f @ellisonbg More work on getting rid of ipmaker.
ellisonbg authored
551 default_banner_parts = [
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
552 'Python %s\n' % (sys.version.split('\n')[0],),
553 'Type "copyright", "credits" or "license" for more information.\n\n',
8608c25 @minrk remove codename from banner
minrk authored
554 'IPython {version} -- An enhanced Interactive Python.\n'.format(
b6facf0 @Carreau add unformal Name for 1.0
Carreau authored
555 version=release.version,
556 ),
8226082 @ellisonbg Massive, crazy refactoring of everything.
ellisonbg authored
557 quick_guide
558 ]
1a8ed8f @ellisonbg More work on getting rid of ipmaker.
ellisonbg authored
559
18358c8 @fperez Add %guiref to give a quick reference to the GUI console.
fperez authored
560 default_gui_banner_parts = default_banner_parts + [gui_note]
561
562 default_banner = ''.join(default_banner_parts)
563
564 default_gui_banner = ''.join(default_gui_banner_parts)
3711a30 @minrk move %guiref out of KernelMagics, into usage
minrk authored
565
566 # page GUI Reference, for use as a magic:
567
568 def page_guiref(arg_s=None):
569 """Show a basic reference about the GUI Console."""
570 from IPython.core import page
300b9f8 @minrk fix a couple typos in Qt from the msg spec update
minrk authored
571 page.page(gui_reference)
3711a30 @minrk move %guiref out of KernelMagics, into usage
minrk authored
572
Something went wrong with that request. Please try again.