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