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 | quick_guide = """\ |
|
332 | quick_guide = """\ | |
541 | ? -> Introduction and overview of IPython's features. |
|
333 | ? -> Introduction and overview of IPython's features. | |
542 | %quickref -> Quick reference. |
|
334 | %quickref -> Quick reference. | |
@@ -562,11 +354,3 b' default_gui_banner_parts = default_banner_parts + [gui_note]' | |||||
562 | default_banner = ''.join(default_banner_parts) |
|
354 | default_banner = ''.join(default_banner_parts) | |
563 |
|
355 | |||
564 | default_gui_banner = ''.join(default_gui_banner_parts) |
|
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