Show More
@@ -329,214 +329,6 b' The following magic functions are currently available:' | |||
|
329 | 329 | |
|
330 | 330 | """ |
|
331 | 331 | |
|
332 | gui_reference = """\ | |
|
333 | =============================== | |
|
334 | The graphical IPython console | |
|
335 | =============================== | |
|
336 | ||
|
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. | |
|
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 | |
|
344 | options available at startup, type ``ipython qtconsole --help`` at the command line. | |
|
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 | |
|
352 | IPython's old terminal behavior, you should find the transition painless, and | |
|
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 | |
|
357 | terminal IPython: single expressions are immediately evaluated, and indented | |
|
358 | blocks are evaluated once a single blank line is entered:: | |
|
359 | ||
|
360 | In [1]: print "Hello IPython!" # Enter was pressed at the end of the line | |
|
361 | Hello IPython! | |
|
362 | ||
|
363 | In [2]: for i in range(10): | |
|
364 | ...: print i, | |
|
365 | ...: | |
|
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 | |
|
376 | cell is executed as if it was a script. An example should clarify this:: | |
|
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 | |
|
383 | ...: | |
|
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 | |
|
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 | |
|
392 | ``Shift-Enter`` anywhere within the cell. | |
|
393 | ||
|
394 | With the up arrow key, you can retrieve previous blocks of input that contain | |
|
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). | |
|
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 | ||
|
410 | The IPython console supports most of the basic Emacs line-oriented keybindings, | |
|
411 | in addition to some of its own. | |
|
412 | ||
|
413 | The keybinding prefixes mean: | |
|
414 | ||
|
415 | - ``C``: Control | |
|
416 | - ``S``: Shift | |
|
417 | - ``M``: Meta (typically the Alt key) | |
|
418 | ||
|
419 | The keybindings themselves are: | |
|
420 | ||
|
421 | - ``Enter``: insert new line (may cause execution, see above). | |
|
422 | - ``C-Enter``: *force* new line, *never* causes execution. | |
|
423 | - ``S-Enter``: *force* execution regardless of where cursor is, no newline added. | |
|
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. | |
|
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. | |
|
437 | - ``C-u``: kill from cursor to the begining of the line. | |
|
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) | |
|
444 | - ``C-d``: delete next character, or exits if input is empty | |
|
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). | |
|
450 | - ``C-+``: increase font size. | |
|
451 | - ``C--``: decrease font size. | |
|
452 | - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X) | |
|
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 | ||
|
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). | |
|
464 | ||
|
465 | - ``vsplit``: the console is made double-tall, and the pager appears on the | |
|
466 | bottom area when needed. You can view its contents while using the terminal. | |
|
467 | ||
|
468 | - ``hsplit``: the console is made double-wide, and the pager appears on the | |
|
469 | right area when needed. You can view its contents while using the terminal. | |
|
470 | ||
|
471 | - ``none``: the console never pages output. | |
|
472 | ||
|
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 | ||
|
480 | In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the | |
|
481 | focus on the pager area). | |
|
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 | |
|
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. | |
|
498 | ||
|
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 | |
|
514 | such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters | |
|
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``. | |
|
524 | ||
|
525 | Inline matplotlib graphics | |
|
526 | ========================== | |
|
527 | ||
|
528 | The IPython console is capable of displaying matplotlib figures inline, in SVG | |
|
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 | |
|
532 | ``display()`` and ``getfigs()`` functions can be used to view plots inline:: | |
|
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 | ||
|
539 | ||
|
540 | 332 | quick_guide = """\ |
|
541 | 333 | ? -> Introduction and overview of IPython's features. |
|
542 | 334 | %quickref -> Quick reference. |
@@ -562,11 +354,3 b' default_gui_banner_parts = default_banner_parts + [gui_note]' | |||
|
562 | 354 | default_banner = ''.join(default_banner_parts) |
|
563 | 355 | |
|
564 | 356 | default_gui_banner = ''.join(default_gui_banner_parts) |
|
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 | |
|
571 | page.page(gui_reference) | |
|
572 |
General Comments 0
You need to be logged in to leave comments.
Login now