##// END OF EJS Templates
move %guiref out of KernelMagics, into usage
MinRK -
Show More
@@ -1,540 +1,548 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] [files]
31 31
32 32 If invoked with no options, it executes all the files listed in sequence
33 33 and exits, use -i to enter interactive mode after running the files. Files
34 34 ending in .py will be treated as normal Python, but files ending in .ipy
35 35 can contain special IPython syntax (magic commands, shell expansions, etc.)
36 36
37 37 Almost all configuration in IPython is available via the command-line. Do
38 38 `ipython --help-all` to see all available options. For persistent
39 39 configuration, look into your `ipython_config.py` configuration file for
40 40 details.
41 41
42 42 This file is typically installed in the `IPYTHONDIR` directory, and there
43 43 is a separate configuration directory for each profile. The default profile
44 44 directory will be located in $IPYTHONDIR/profile_default. For Linux users,
45 45 IPYTHONDIR defaults to `$HOME/.config/ipython`, and for other Unix systems
46 46 to `$HOME/.ipython`. For Windows users, $HOME resolves to C:\\Documents
47 47 and Settings\\YourUserName in most instances.
48 48
49 49 To initialize a profile with the default configuration file, do::
50 50
51 51 $> ipython profile create
52 52
53 53 and start editing `IPYTHONDIR/profile_default/ipython_config.py`
54 54
55 55 In IPython's documentation, we will refer to this directory as
56 56 `IPYTHONDIR`, you can change its default location by creating an
57 57 environment variable with this name and setting it to the desired path.
58 58
59 59 For more information, see the manual available in HTML and PDF in your
60 60 installation, or online at http://ipython.org/documentation.html.
61 61 """
62 62
63 63 interactive_usage = """
64 64 IPython -- An enhanced Interactive Python
65 65 =========================================
66 66
67 67 IPython offers a combination of convenient shell features, special commands
68 68 and a history mechanism for both input (command history) and output (results
69 69 caching, similar to Mathematica). It is intended to be a fully compatible
70 70 replacement for the standard Python interpreter, while offering vastly
71 71 improved functionality and flexibility.
72 72
73 73 At your system command line, type 'ipython -h' to see the command line
74 74 options available. This document only describes interactive features.
75 75
76 76 MAIN FEATURES
77 77
78 78 * Access to the standard Python help. As of Python 2.1, a help system is
79 79 available with access to object docstrings and the Python manuals. Simply
80 80 type 'help' (no quotes) to access it.
81 81
82 82 * Magic commands: type %magic for information on the magic subsystem.
83 83
84 84 * System command aliases, via the %alias command or the configuration file(s).
85 85
86 86 * Dynamic object information:
87 87
88 88 Typing ?word or word? prints detailed information about an object. If
89 89 certain strings in the object are too long (docstrings, code, etc.) they get
90 90 snipped in the center for brevity.
91 91
92 92 Typing ??word or word?? gives access to the full information without
93 93 snipping long strings. Long strings are sent to the screen through the less
94 94 pager if longer than the screen, printed otherwise.
95 95
96 96 The ?/?? system gives access to the full source code for any object (if
97 97 available), shows function prototypes and other useful information.
98 98
99 99 If you just want to see an object's docstring, type '%pdoc object' (without
100 100 quotes, and without % if you have automagic on).
101 101
102 102 Both %pdoc and ?/?? give you access to documentation even on things which are
103 103 not explicitely defined. Try for example typing {}.get? or after import os,
104 104 type os.path.abspath??. The magic functions %pdef, %source and %file operate
105 105 similarly.
106 106
107 107 * Completion in the local namespace, by typing TAB at the prompt.
108 108
109 109 At any time, hitting tab will complete any available python commands or
110 110 variable names, and show you a list of the possible completions if there's
111 111 no unambiguous one. It will also complete filenames in the current directory.
112 112
113 113 This feature requires the readline and rlcomplete modules, so it won't work
114 114 if your Python lacks readline support (such as under Windows).
115 115
116 116 * Search previous command history in two ways (also requires readline):
117 117
118 118 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
119 119 search through only the history items that match what you've typed so
120 120 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
121 121 normal arrow keys.
122 122
123 123 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
124 124 your history for lines that match what you've typed so far, completing as
125 125 much as it can.
126 126
127 127 - %hist: search history by index (this does *not* require readline).
128 128
129 129 * Persistent command history across sessions.
130 130
131 131 * Logging of input with the ability to save and restore a working session.
132 132
133 133 * System escape with !. Typing !ls will run 'ls' in the current directory.
134 134
135 135 * The reload command does a 'deep' reload of a module: changes made to the
136 136 module since you imported will actually be available without having to exit.
137 137
138 138 * Verbose and colored exception traceback printouts. See the magic xmode and
139 139 xcolor functions for details (just type %magic).
140 140
141 141 * Input caching system:
142 142
143 143 IPython offers numbered prompts (In/Out) with input and output caching. All
144 144 input is saved and can be retrieved as variables (besides the usual arrow
145 145 key recall).
146 146
147 147 The following GLOBAL variables always exist (so don't overwrite them!):
148 148 _i: stores previous input.
149 149 _ii: next previous.
150 150 _iii: next-next previous.
151 151 _ih : a list of all input _ih[n] is the input from line n.
152 152
153 153 Additionally, global variables named _i<n> are dynamically created (<n>
154 154 being the prompt counter), such that _i<n> == _ih[<n>]
155 155
156 156 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
157 157
158 158 You can create macros which contain multiple input lines from this history,
159 159 for later re-execution, with the %macro function.
160 160
161 161 The history function %hist allows you to see any part of your input history
162 162 by printing a range of the _i variables. Note that inputs which contain
163 163 magic functions (%) appear in the history with a prepended comment. This is
164 164 because they aren't really valid Python code, so you can't exec them.
165 165
166 166 * Output caching system:
167 167
168 168 For output that is returned from actions, a system similar to the input
169 169 cache exists but using _ instead of _i. Only actions that produce a result
170 170 (NOT assignments, for example) are cached. If you are familiar with
171 171 Mathematica, IPython's _ variables behave exactly like Mathematica's %
172 172 variables.
173 173
174 174 The following GLOBAL variables always exist (so don't overwrite them!):
175 175 _ (one underscore): previous output.
176 176 __ (two underscores): next previous.
177 177 ___ (three underscores): next-next previous.
178 178
179 179 Global variables named _<n> are dynamically created (<n> being the prompt
180 180 counter), such that the result of output <n> is always available as _<n>.
181 181
182 182 Finally, a global dictionary named _oh exists with entries for all lines
183 183 which generated output.
184 184
185 185 * Directory history:
186 186
187 187 Your history of visited directories is kept in the global list _dh, and the
188 188 magic %cd command can be used to go to any entry in that list.
189 189
190 190 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
191 191
192 192 1. Auto-parentheses
193 193 Callable objects (i.e. functions, methods, etc) can be invoked like
194 194 this (notice the commas between the arguments):
195 195 In [1]: callable_ob arg1, arg2, arg3
196 196 and the input will be translated to this:
197 197 ------> callable_ob(arg1, arg2, arg3)
198 198 This feature is off by default (in rare cases it can produce
199 199 undesirable side-effects), but you can activate it at the command-line
200 200 by starting IPython with `--autocall 1`, set it permanently in your
201 201 configuration file, or turn on at runtime with `%autocall 1`.
202 202
203 203 You can force auto-parentheses by using '/' as the first character
204 204 of a line. For example:
205 205 In [1]: /globals # becomes 'globals()'
206 206 Note that the '/' MUST be the first character on the line! This
207 207 won't work:
208 208 In [2]: print /globals # syntax error
209 209
210 210 In most cases the automatic algorithm should work, so you should
211 211 rarely need to explicitly invoke /. One notable exception is if you
212 212 are trying to call a function with a list of tuples as arguments (the
213 213 parenthesis will confuse IPython):
214 214 In [1]: zip (1,2,3),(4,5,6) # won't work
215 215 but this will work:
216 216 In [2]: /zip (1,2,3),(4,5,6)
217 217 ------> zip ((1,2,3),(4,5,6))
218 218 Out[2]= [(1, 4), (2, 5), (3, 6)]
219 219
220 220 IPython tells you that it has altered your command line by
221 221 displaying the new command line preceded by -->. e.g.:
222 222 In [18]: callable list
223 223 -------> callable (list)
224 224
225 225 2. Auto-Quoting
226 226 You can force auto-quoting of a function's arguments by using ',' as
227 227 the first character of a line. For example:
228 228 In [1]: ,my_function /home/me # becomes my_function("/home/me")
229 229
230 230 If you use ';' instead, the whole argument is quoted as a single
231 231 string (while ',' splits on whitespace):
232 232 In [2]: ,my_function a b c # becomes my_function("a","b","c")
233 233 In [3]: ;my_function a b c # becomes my_function("a b c")
234 234
235 235 Note that the ',' MUST be the first character on the line! This
236 236 won't work:
237 237 In [4]: x = ,my_function /home/me # syntax error
238 238 """
239 239
240 240 interactive_usage_min = """\
241 241 An enhanced console for Python.
242 242 Some of its features are:
243 243 - Readline support if the readline library is present.
244 244 - Tab completion in the local namespace.
245 245 - Logging of input, see command-line options.
246 246 - System shell escape via ! , eg !ls.
247 247 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
248 248 - Keeps track of locally defined variables via %who, %whos.
249 249 - Show object information with a ? eg ?x or x? (use ?? for more info).
250 250 """
251 251
252 252 quick_reference = r"""
253 253 IPython -- An enhanced Interactive Python - Quick Reference Card
254 254 ================================================================
255 255
256 256 obj?, obj?? : Get help, or more help for object (also works as
257 257 ?obj, ??obj).
258 258 ?foo.*abc* : List names in 'foo' containing 'abc' in them.
259 259 %magic : Information about IPython's 'magic' % functions.
260 260
261 261 Magic functions are prefixed by % or %%, and typically take their arguments
262 262 without parentheses, quotes or even commas for convenience. Line magics take a
263 263 single % and cell magics are prefixed with two %%.
264 264
265 265 Example magic function calls:
266 266
267 267 %alias d ls -F : 'd' is now an alias for 'ls -F'
268 268 alias d ls -F : Works if 'alias' not a python name
269 269 alist = %alias : Get list of aliases to 'alist'
270 270 cd /usr/share : Obvious. cd -<tab> to choose from visited dirs.
271 271 %cd?? : See help AND source for magic %cd
272 272 %timeit x=10 : time the 'x=10' statement with high precision.
273 273 %%timeit x=2**100
274 274 x**100 : time 'x*100' with a setup of 'x=2**100'; setup code is not
275 275 counted. This is an example of a cell magic.
276 276
277 277 System commands:
278 278
279 279 !cp a.txt b/ : System command escape, calls os.system()
280 280 cp a.txt b/ : after %rehashx, most system commands work without !
281 281 cp ${f}.txt $bar : Variable expansion in magics and system commands
282 282 files = !ls /usr : Capture sytem command output
283 283 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
284 284
285 285 History:
286 286
287 287 _i, _ii, _iii : Previous, next previous, next next previous input
288 288 _i4, _ih[2:5] : Input history line 4, lines 2-4
289 289 exec _i81 : Execute input history line #81 again
290 290 %rep 81 : Edit input history line #81
291 291 _, __, ___ : previous, next previous, next next previous output
292 292 _dh : Directory history
293 293 _oh : Output history
294 294 %hist : Command history. '%hist -g foo' search history for 'foo'
295 295
296 296 Autocall:
297 297
298 298 f 1,2 : f(1,2) # Off by default, enable with %autocall magic.
299 299 /f 1,2 : f(1,2) (forced autoparen)
300 300 ,f 1 2 : f("1","2")
301 301 ;f 1 2 : f("1 2")
302 302
303 303 Remember: TAB completion works in many contexts, not just file names
304 304 or python names.
305 305
306 306 The following magic functions are currently available:
307 307
308 308 """
309 309
310 310 gui_reference = """\
311 311 ===============================
312 312 The graphical IPython console
313 313 ===============================
314 314
315 315 This console is designed to emulate the look, feel and workflow of a terminal
316 316 environment, while adding a number of enhancements that are simply not possible
317 317 in a real terminal, such as inline syntax highlighting, true multiline editing,
318 318 inline graphics and much more.
319 319
320 320 This quick reference document contains the basic information you'll need to
321 321 know to make the most efficient use of it. For the various command line
322 322 options available at startup, type ``ipython qtconsole --help`` at the command line.
323 323
324 324
325 325 Multiline editing
326 326 =================
327 327
328 328 The graphical console is capable of true multiline editing, but it also tries
329 329 to behave intuitively like a terminal when possible. If you are used to
330 330 IPython's old terminal behavior, you should find the transition painless, and
331 331 once you learn a few basic keybindings it will be a much more efficient
332 332 environment.
333 333
334 334 For single expressions or indented blocks, the console behaves almost like the
335 335 terminal IPython: single expressions are immediately evaluated, and indented
336 336 blocks are evaluated once a single blank line is entered::
337 337
338 338 In [1]: print "Hello IPython!" # Enter was pressed at the end of the line
339 339 Hello IPython!
340 340
341 341 In [2]: for i in range(10):
342 342 ...: print i,
343 343 ...:
344 344 0 1 2 3 4 5 6 7 8 9
345 345
346 346 If you want to enter more than one expression in a single input block
347 347 (something not possible in the terminal), you can use ``Control-Enter`` at the
348 348 end of your first line instead of ``Enter``. At that point the console goes
349 349 into 'cell mode' and even if your inputs are not indented, it will continue
350 350 accepting arbitrarily many lines until either you enter an extra blank line or
351 351 you hit ``Shift-Enter`` (the key binding that forces execution). When a
352 352 multiline cell is entered, IPython analyzes it and executes its code producing
353 353 an ``Out[n]`` prompt only for the last expression in it, while the rest of the
354 354 cell is executed as if it was a script. An example should clarify this::
355 355
356 356 In [3]: x=1 # Hit C-Enter here
357 357 ...: y=2 # from now on, regular Enter is sufficient
358 358 ...: z=3
359 359 ...: x**2 # This does *not* produce an Out[] value
360 360 ...: x+y+z # Only the last expression does
361 361 ...:
362 362 Out[3]: 6
363 363
364 364 The behavior where an extra blank line forces execution is only active if you
365 365 are actually typing at the keyboard each line, and is meant to make it mimic
366 366 the IPython terminal behavior. If you paste a long chunk of input (for example
367 367 a long script copied form an editor or web browser), it can contain arbitrarily
368 368 many intermediate blank lines and they won't cause any problems. As always,
369 369 you can then make it execute by appending a blank line *at the end* or hitting
370 370 ``Shift-Enter`` anywhere within the cell.
371 371
372 372 With the up arrow key, you can retrieve previous blocks of input that contain
373 373 multiple lines. You can move inside of a multiline cell like you would in any
374 374 text editor. When you want it executed, the simplest thing to do is to hit the
375 375 force execution key, ``Shift-Enter`` (though you can also navigate to the end
376 376 and append a blank line by using ``Enter`` twice).
377 377
378 378 If you've edited a multiline cell and accidentally navigate out of it with the
379 379 up or down arrow keys, IPython will clear the cell and replace it with the
380 380 contents of the one above or below that you navigated to. If this was an
381 381 accident and you want to retrieve the cell you were editing, use the Undo
382 382 keybinding, ``Control-z``.
383 383
384 384
385 385 Key bindings
386 386 ============
387 387
388 388 The IPython console supports most of the basic Emacs line-oriented keybindings,
389 389 in addition to some of its own.
390 390
391 391 The keybinding prefixes mean:
392 392
393 393 - ``C``: Control
394 394 - ``S``: Shift
395 395 - ``M``: Meta (typically the Alt key)
396 396
397 397 The keybindings themselves are:
398 398
399 399 - ``Enter``: insert new line (may cause execution, see above).
400 400 - ``C-Enter``: *force* new line, *never* causes execution.
401 401 - ``S-Enter``: *force* execution regardless of where cursor is, no newline added.
402 402 - ``Up``: step backwards through the history.
403 403 - ``Down``: step forwards through the history.
404 404 - ``S-Up``: search backwards through the history (like ``C-r`` in bash).
405 405 - ``S-Down``: search forwards through the history.
406 406 - ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped).
407 407 - ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped).
408 408 - ``C-v``: paste text from clipboard.
409 409 - ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows).
410 410 - ``C-S-z``: redo.
411 411 - ``C-o``: move to 'other' area, between pager and terminal.
412 412 - ``C-l``: clear terminal.
413 413 - ``C-a``: go to beginning of line.
414 414 - ``C-e``: go to end of line.
415 415 - ``C-u``: kill from cursor to the begining of the line.
416 416 - ``C-k``: kill from cursor to the end of the line.
417 417 - ``C-y``: yank (paste)
418 418 - ``C-p``: previous line (like up arrow)
419 419 - ``C-n``: next line (like down arrow)
420 420 - ``C-f``: forward (like right arrow)
421 421 - ``C-b``: back (like left arrow)
422 422 - ``C-d``: delete next character, or exits if input is empty
423 423 - ``M-<``: move to the beginning of the input region.
424 424 - ``M->``: move to the end of the input region.
425 425 - ``M-d``: delete next word.
426 426 - ``M-Backspace``: delete previous word.
427 427 - ``C-.``: force a kernel restart (a confirmation dialog appears).
428 428 - ``C-+``: increase font size.
429 429 - ``C--``: decrease font size.
430 430 - ``C-M-Space``: toggle full screen. (Command-Control-Space on Mac OS X)
431 431
432 432 The IPython pager
433 433 =================
434 434
435 435 IPython will show long blocks of text from many sources using a builtin pager.
436 436 You can control where this pager appears with the ``--paging`` command-line
437 437 flag:
438 438
439 439 - ``inside`` [default]: the pager is overlaid on top of the main terminal. You
440 440 must quit the pager to get back to the terminal (similar to how a pager such
441 441 as ``less`` or ``more`` works).
442 442
443 443 - ``vsplit``: the console is made double-tall, and the pager appears on the
444 444 bottom area when needed. You can view its contents while using the terminal.
445 445
446 446 - ``hsplit``: the console is made double-wide, and the pager appears on the
447 447 right area when needed. You can view its contents while using the terminal.
448 448
449 449 - ``none``: the console never pages output.
450 450
451 451 If you use the vertical or horizontal paging modes, you can navigate between
452 452 terminal and pager as follows:
453 453
454 454 - Tab key: goes from pager to terminal (but not the other way around).
455 455 - Control-o: goes from one to another always.
456 456 - Mouse: click on either.
457 457
458 458 In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the
459 459 focus on the pager area).
460 460
461 461 Running subprocesses
462 462 ====================
463 463
464 464 The graphical IPython console uses the ``pexpect`` module to run subprocesses
465 465 when you type ``!command``. This has a number of advantages (true asynchronous
466 466 output from subprocesses as well as very robust termination of rogue
467 467 subprocesses with ``Control-C``), as well as some limitations. The main
468 468 limitation is that you can *not* interact back with the subprocess, so anything
469 469 that invokes a pager or expects you to type input into it will block and hang
470 470 (you can kill it with ``Control-C``).
471 471
472 472 We have provided as magics ``%less`` to page files (aliased to ``%more``),
473 473 ``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the
474 474 most common commands you'd want to call in your subshell and that would cause
475 475 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
476 476
477 477 Display
478 478 =======
479 479
480 480 The IPython console can now display objects in a variety of formats, including
481 481 HTML, PNG and SVG. This is accomplished using the display functions in
482 482 ``IPython.core.display``::
483 483
484 484 In [4]: from IPython.core.display import display, display_html
485 485
486 486 In [5]: from IPython.core.display import display_png, display_svg
487 487
488 488 Python objects can simply be passed to these functions and the appropriate
489 489 representations will be displayed in the console as long as the objects know
490 490 how to compute those representations. The easiest way of teaching objects how
491 491 to format themselves in various representations is to define special methods
492 492 such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters
493 493 can also be given custom formatter functions for various types::
494 494
495 495 In [6]: ip = get_ipython()
496 496
497 497 In [7]: html_formatter = ip.display_formatter.formatters['text/html']
498 498
499 499 In [8]: html_formatter.for_type(Foo, foo_to_html)
500 500
501 501 For further details, see ``IPython.core.formatters``.
502 502
503 503 Inline matplotlib graphics
504 504 ==========================
505 505
506 506 The IPython console is capable of displaying matplotlib figures inline, in SVG
507 507 or PNG format. If started with the ``pylab=inline``, then all figures are
508 508 rendered inline automatically (PNG by default). If started with ``--pylab``
509 509 or ``pylab=<your backend>``, then a GUI backend will be used, but IPython's
510 510 ``display()`` and ``getfigs()`` functions can be used to view plots inline::
511 511
512 512 In [9]: display(*getfigs()) # display all figures inline
513 513
514 514 In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
515 515 """
516 516
517 517
518 518 quick_guide = """\
519 519 ? -> Introduction and overview of IPython's features.
520 520 %quickref -> Quick reference.
521 521 help -> Python's own help system.
522 522 object? -> Details about 'object', use 'object??' for extra details.
523 523 """
524 524
525 525 gui_note = """\
526 526 %guiref -> A brief reference about the graphical user interface.
527 527 """
528 528
529 529 default_banner_parts = [
530 530 'Python %s\n' % (sys.version.split('\n')[0],),
531 531 'Type "copyright", "credits" or "license" for more information.\n\n',
532 532 'IPython %s -- An enhanced Interactive Python.\n' % (release.version,),
533 533 quick_guide
534 534 ]
535 535
536 536 default_gui_banner_parts = default_banner_parts + [gui_note]
537 537
538 538 default_banner = ''.join(default_banner_parts)
539 539
540 540 default_gui_banner = ''.join(default_gui_banner_parts)
541
542 # page GUI Reference, for use as a magic:
543
544 def page_guiref(arg_s=None):
545 """Show a basic reference about the GUI Console."""
546 from IPython.core import page
547 page.page(gui_reference, auto_html=True)
548
@@ -1,560 +1,549 b''
1 1 """A ZMQ-based subclass of InteractiveShell.
2 2
3 3 This code is meant to ease the refactoring of the base InteractiveShell into
4 4 something with a cleaner architecture for 2-process use, without actually
5 5 breaking InteractiveShell itself. So we're doing something a bit ugly, where
6 6 we subclass and override what we want to fix. Once this is working well, we
7 7 can go back to the base class and refactor the code for a cleaner inheritance
8 8 implementation that doesn't rely on so much monkeypatching.
9 9
10 10 But this lets us maintain a fully working IPython as we develop the new
11 11 machinery. This should thus be thought of as scaffolding.
12 12 """
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16 from __future__ import print_function
17 17
18 18 # Stdlib
19 19 import os
20 20 import sys
21 21 import time
22 22
23 23 # System library imports
24 24 from zmq.eventloop import ioloop
25 25
26 26 # Our own
27 27 from IPython.core.interactiveshell import (
28 28 InteractiveShell, InteractiveShellABC
29 29 )
30 30 from IPython.core import page
31 31 from IPython.core.autocall import ZMQExitAutocall
32 32 from IPython.core.displaypub import DisplayPublisher
33 33 from IPython.core.magics import MacroToEdit, CodeMagics
34 34 from IPython.core.magic import magics_class, line_magic, Magics
35 35 from IPython.core.payloadpage import install_payload_page
36 36 from IPython.lib.kernel import (
37 37 get_connection_file, get_connection_info, connect_qtconsole
38 38 )
39 39 from IPython.testing.skipdoctest import skip_doctest
40 40 from IPython.utils import io
41 41 from IPython.utils.jsonutil import json_clean
42 42 from IPython.utils.process import arg_split
43 43 from IPython.utils.traitlets import Instance, Type, Dict, CBool, CBytes
44 44 from IPython.utils.warn import warn, error
45 45 from IPython.zmq.displayhook import ZMQShellDisplayHook, _encode_binary
46 46 from IPython.zmq.session import extract_header
47 47 from session import Session
48 48
49 49 #-----------------------------------------------------------------------------
50 50 # Functions and classes
51 51 #-----------------------------------------------------------------------------
52 52
53 53 class ZMQDisplayPublisher(DisplayPublisher):
54 54 """A display publisher that publishes data using a ZeroMQ PUB socket."""
55 55
56 56 session = Instance(Session)
57 57 pub_socket = Instance('zmq.Socket')
58 58 parent_header = Dict({})
59 59 topic = CBytes(b'displaypub')
60 60
61 61 def set_parent(self, parent):
62 62 """Set the parent for outbound messages."""
63 63 self.parent_header = extract_header(parent)
64 64
65 65 def _flush_streams(self):
66 66 """flush IO Streams prior to display"""
67 67 sys.stdout.flush()
68 68 sys.stderr.flush()
69 69
70 70 def publish(self, source, data, metadata=None):
71 71 self._flush_streams()
72 72 if metadata is None:
73 73 metadata = {}
74 74 self._validate_data(source, data, metadata)
75 75 content = {}
76 76 content['source'] = source
77 77 content['data'] = _encode_binary(data)
78 78 content['metadata'] = metadata
79 79 self.session.send(
80 80 self.pub_socket, u'display_data', json_clean(content),
81 81 parent=self.parent_header, ident=self.topic,
82 82 )
83 83
84 84 def clear_output(self, stdout=True, stderr=True, other=True):
85 85 content = dict(stdout=stdout, stderr=stderr, other=other)
86 86
87 87 if stdout:
88 88 print('\r', file=sys.stdout, end='')
89 89 if stderr:
90 90 print('\r', file=sys.stderr, end='')
91 91
92 92 self._flush_streams()
93 93
94 94 self.session.send(
95 95 self.pub_socket, u'clear_output', content,
96 96 parent=self.parent_header, ident=self.topic,
97 97 )
98 98
99 99 @magics_class
100 100 class KernelMagics(Magics):
101 101 #------------------------------------------------------------------------
102 102 # Magic overrides
103 103 #------------------------------------------------------------------------
104 104 # Once the base class stops inheriting from magic, this code needs to be
105 105 # moved into a separate machinery as well. For now, at least isolate here
106 106 # the magics which this class needs to implement differently from the base
107 107 # class, or that are unique to it.
108 108
109 109 @line_magic
110 110 def doctest_mode(self, parameter_s=''):
111 111 """Toggle doctest mode on and off.
112 112
113 113 This mode is intended to make IPython behave as much as possible like a
114 114 plain Python shell, from the perspective of how its prompts, exceptions
115 115 and output look. This makes it easy to copy and paste parts of a
116 116 session into doctests. It does so by:
117 117
118 118 - Changing the prompts to the classic ``>>>`` ones.
119 119 - Changing the exception reporting mode to 'Plain'.
120 120 - Disabling pretty-printing of output.
121 121
122 122 Note that IPython also supports the pasting of code snippets that have
123 123 leading '>>>' and '...' prompts in them. This means that you can paste
124 124 doctests from files or docstrings (even if they have leading
125 125 whitespace), and the code will execute correctly. You can then use
126 126 '%history -t' to see the translated history; this will give you the
127 127 input after removal of all the leading prompts and whitespace, which
128 128 can be pasted back into an editor.
129 129
130 130 With these features, you can switch into this mode easily whenever you
131 131 need to do testing and changes to doctests, without having to leave
132 132 your existing IPython session.
133 133 """
134 134
135 135 from IPython.utils.ipstruct import Struct
136 136
137 137 # Shorthands
138 138 shell = self.shell
139 139 disp_formatter = self.shell.display_formatter
140 140 ptformatter = disp_formatter.formatters['text/plain']
141 141 # dstore is a data store kept in the instance metadata bag to track any
142 142 # changes we make, so we can undo them later.
143 143 dstore = shell.meta.setdefault('doctest_mode', Struct())
144 144 save_dstore = dstore.setdefault
145 145
146 146 # save a few values we'll need to recover later
147 147 mode = save_dstore('mode', False)
148 148 save_dstore('rc_pprint', ptformatter.pprint)
149 149 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
150 150 save_dstore('xmode', shell.InteractiveTB.mode)
151 151
152 152 if mode == False:
153 153 # turn on
154 154 ptformatter.pprint = False
155 155 disp_formatter.plain_text_only = True
156 156 shell.magic('xmode Plain')
157 157 else:
158 158 # turn off
159 159 ptformatter.pprint = dstore.rc_pprint
160 160 disp_formatter.plain_text_only = dstore.rc_plain_text_only
161 161 shell.magic("xmode " + dstore.xmode)
162 162
163 163 # Store new mode and inform on console
164 164 dstore.mode = bool(1-int(mode))
165 165 mode_label = ['OFF','ON'][dstore.mode]
166 166 print('Doctest mode is:', mode_label)
167 167
168 168 # Send the payload back so that clients can modify their prompt display
169 169 payload = dict(
170 170 source='IPython.zmq.zmqshell.ZMQInteractiveShell.doctest_mode',
171 171 mode=dstore.mode)
172 172 shell.payload_manager.write_payload(payload)
173 173
174 174
175 175 _find_edit_target = CodeMagics._find_edit_target
176 176
177 177 @skip_doctest
178 178 @line_magic
179 179 def edit(self, parameter_s='', last_call=['','']):
180 180 """Bring up an editor and execute the resulting code.
181 181
182 182 Usage:
183 183 %edit [options] [args]
184 184
185 185 %edit runs an external text editor. You will need to set the command for
186 186 this editor via the ``TerminalInteractiveShell.editor`` option in your
187 187 configuration file before it will work.
188 188
189 189 This command allows you to conveniently edit multi-line code right in
190 190 your IPython session.
191 191
192 192 If called without arguments, %edit opens up an empty editor with a
193 193 temporary file and will execute the contents of this file when you
194 194 close it (don't forget to save it!).
195 195
196 196
197 197 Options:
198 198
199 199 -n <number>: open the editor at a specified line number. By default,
200 200 the IPython editor hook uses the unix syntax 'editor +N filename', but
201 201 you can configure this by providing your own modified hook if your
202 202 favorite editor supports line-number specifications with a different
203 203 syntax.
204 204
205 205 -p: this will call the editor with the same data as the previous time
206 206 it was used, regardless of how long ago (in your current session) it
207 207 was.
208 208
209 209 -r: use 'raw' input. This option only applies to input taken from the
210 210 user's history. By default, the 'processed' history is used, so that
211 211 magics are loaded in their transformed version to valid Python. If
212 212 this option is given, the raw input as typed as the command line is
213 213 used instead. When you exit the editor, it will be executed by
214 214 IPython's own processor.
215 215
216 216 -x: do not execute the edited code immediately upon exit. This is
217 217 mainly useful if you are editing programs which need to be called with
218 218 command line arguments, which you can then do using %run.
219 219
220 220
221 221 Arguments:
222 222
223 223 If arguments are given, the following possibilites exist:
224 224
225 225 - The arguments are numbers or pairs of colon-separated numbers (like
226 226 1 4:8 9). These are interpreted as lines of previous input to be
227 227 loaded into the editor. The syntax is the same of the %macro command.
228 228
229 229 - If the argument doesn't start with a number, it is evaluated as a
230 230 variable and its contents loaded into the editor. You can thus edit
231 231 any string which contains python code (including the result of
232 232 previous edits).
233 233
234 234 - If the argument is the name of an object (other than a string),
235 235 IPython will try to locate the file where it was defined and open the
236 236 editor at the point where it is defined. You can use `%edit function`
237 237 to load an editor exactly at the point where 'function' is defined,
238 238 edit it and have the file be executed automatically.
239 239
240 240 If the object is a macro (see %macro for details), this opens up your
241 241 specified editor with a temporary file containing the macro's data.
242 242 Upon exit, the macro is reloaded with the contents of the file.
243 243
244 244 Note: opening at an exact line is only supported under Unix, and some
245 245 editors (like kedit and gedit up to Gnome 2.8) do not understand the
246 246 '+NUMBER' parameter necessary for this feature. Good editors like
247 247 (X)Emacs, vi, jed, pico and joe all do.
248 248
249 249 - If the argument is not found as a variable, IPython will look for a
250 250 file with that name (adding .py if necessary) and load it into the
251 251 editor. It will execute its contents with execfile() when you exit,
252 252 loading any code in the file into your interactive namespace.
253 253
254 254 After executing your code, %edit will return as output the code you
255 255 typed in the editor (except when it was an existing file). This way
256 256 you can reload the code in further invocations of %edit as a variable,
257 257 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
258 258 the output.
259 259
260 260 Note that %edit is also available through the alias %ed.
261 261
262 262 This is an example of creating a simple function inside the editor and
263 263 then modifying it. First, start up the editor:
264 264
265 265 In [1]: ed
266 266 Editing... done. Executing edited code...
267 267 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
268 268
269 269 We can then call the function foo():
270 270
271 271 In [2]: foo()
272 272 foo() was defined in an editing session
273 273
274 274 Now we edit foo. IPython automatically loads the editor with the
275 275 (temporary) file where foo() was previously defined:
276 276
277 277 In [3]: ed foo
278 278 Editing... done. Executing edited code...
279 279
280 280 And if we call foo() again we get the modified version:
281 281
282 282 In [4]: foo()
283 283 foo() has now been changed!
284 284
285 285 Here is an example of how to edit a code snippet successive
286 286 times. First we call the editor:
287 287
288 288 In [5]: ed
289 289 Editing... done. Executing edited code...
290 290 hello
291 291 Out[5]: "print 'hello'n"
292 292
293 293 Now we call it again with the previous output (stored in _):
294 294
295 295 In [6]: ed _
296 296 Editing... done. Executing edited code...
297 297 hello world
298 298 Out[6]: "print 'hello world'n"
299 299
300 300 Now we call it with the output #8 (stored in _8, also as Out[8]):
301 301
302 302 In [7]: ed _8
303 303 Editing... done. Executing edited code...
304 304 hello again
305 305 Out[7]: "print 'hello again'n"
306 306 """
307 307
308 308 opts,args = self.parse_options(parameter_s,'prn:')
309 309
310 310 try:
311 311 filename, lineno, _ = CodeMagics._find_edit_target(self.shell, args, opts, last_call)
312 312 except MacroToEdit as e:
313 313 # TODO: Implement macro editing over 2 processes.
314 314 print("Macro editing not yet implemented in 2-process model.")
315 315 return
316 316
317 317 # Make sure we send to the client an absolute path, in case the working
318 318 # directory of client and kernel don't match
319 319 filename = os.path.abspath(filename)
320 320
321 321 payload = {
322 322 'source' : 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic',
323 323 'filename' : filename,
324 324 'line_number' : lineno
325 325 }
326 326 self.shell.payload_manager.write_payload(payload)
327 327
328 328 # A few magics that are adapted to the specifics of using pexpect and a
329 329 # remote terminal
330 330
331 331 @line_magic
332 332 def clear(self, arg_s):
333 333 """Clear the terminal."""
334 334 if os.name == 'posix':
335 335 self.shell.system("clear")
336 336 else:
337 337 self.shell.system("cls")
338 338
339 339 if os.name == 'nt':
340 340 # This is the usual name in windows
341 341 cls = line_magic('cls')(clear)
342 342
343 343 # Terminal pagers won't work over pexpect, but we do have our own pager
344 344
345 345 @line_magic
346 346 def less(self, arg_s):
347 347 """Show a file through the pager.
348 348
349 349 Files ending in .py are syntax-highlighted."""
350 350 cont = open(arg_s).read()
351 351 if arg_s.endswith('.py'):
352 352 cont = self.shell.pycolorize(cont)
353 353 page.page(cont)
354 354
355 355 more = line_magic('more')(less)
356 356
357 357 # Man calls a pager, so we also need to redefine it
358 358 if os.name == 'posix':
359 359 @line_magic
360 360 def man(self, arg_s):
361 361 """Find the man page for the given command and display in pager."""
362 362 page.page(self.shell.getoutput('man %s | col -b' % arg_s,
363 363 split=False))
364 364
365 # FIXME: this is specific to the GUI, so we should let the gui app load
366 # magics at startup that are only for the gui. Once the gui app has proper
367 # profile and configuration management, we can have it initialize a kernel
368 # with a special config file that provides these.
369
370 @line_magic
371 def guiref(self, arg_s):
372 """Show a basic reference about the GUI console."""
373 from IPython.core.usage import gui_reference
374 page.page(gui_reference, auto_html=True)
375
376 365 @line_magic
377 366 def connect_info(self, arg_s):
378 367 """Print information for connecting other clients to this kernel
379 368
380 369 It will print the contents of this session's connection file, as well as
381 370 shortcuts for local clients.
382 371
383 372 In the simplest case, when called from the most recently launched kernel,
384 373 secondary clients can be connected, simply with:
385 374
386 375 $> ipython <app> --existing
387 376
388 377 """
389 378
390 379 from IPython.core.application import BaseIPythonApplication as BaseIPApp
391 380
392 381 if BaseIPApp.initialized():
393 382 app = BaseIPApp.instance()
394 383 security_dir = app.profile_dir.security_dir
395 384 profile = app.profile
396 385 else:
397 386 profile = 'default'
398 387 security_dir = ''
399 388
400 389 try:
401 390 connection_file = get_connection_file()
402 391 info = get_connection_info(unpack=False)
403 392 except Exception as e:
404 393 error("Could not get connection info: %r" % e)
405 394 return
406 395
407 396 # add profile flag for non-default profile
408 397 profile_flag = "--profile %s" % profile if profile != 'default' else ""
409 398
410 399 # if it's in the security dir, truncate to basename
411 400 if security_dir == os.path.dirname(connection_file):
412 401 connection_file = os.path.basename(connection_file)
413 402
414 403
415 404 print (info + '\n')
416 405 print ("Paste the above JSON into a file, and connect with:\n"
417 406 " $> ipython <app> --existing <file>\n"
418 407 "or, if you are local, you can connect with just:\n"
419 408 " $> ipython <app> --existing {0} {1}\n"
420 409 "or even just:\n"
421 410 " $> ipython <app> --existing {1}\n"
422 411 "if this is the most recent IPython session you have started.".format(
423 412 connection_file, profile_flag
424 413 )
425 414 )
426 415
427 416 @line_magic
428 417 def qtconsole(self, arg_s):
429 418 """Open a qtconsole connected to this kernel.
430 419
431 420 Useful for connecting a qtconsole to running notebooks, for better
432 421 debugging.
433 422 """
434 423 try:
435 424 p = connect_qtconsole(argv=arg_split(arg_s, os.name=='posix'))
436 425 except Exception as e:
437 426 error("Could not start qtconsole: %r" % e)
438 427 return
439 428
440 429
441 430 class ZMQInteractiveShell(InteractiveShell):
442 431 """A subclass of InteractiveShell for ZMQ."""
443 432
444 433 displayhook_class = Type(ZMQShellDisplayHook)
445 434 display_pub_class = Type(ZMQDisplayPublisher)
446 435
447 436 # Override the traitlet in the parent class, because there's no point using
448 437 # readline for the kernel. Can be removed when the readline code is moved
449 438 # to the terminal frontend.
450 439 colors_force = CBool(True)
451 440 readline_use = CBool(False)
452 441 # autoindent has no meaning in a zmqshell, and attempting to enable it
453 442 # will print a warning in the absence of readline.
454 443 autoindent = CBool(False)
455 444
456 445 exiter = Instance(ZMQExitAutocall)
457 446 def _exiter_default(self):
458 447 return ZMQExitAutocall(self)
459 448
460 449 def _exit_now_changed(self, name, old, new):
461 450 """stop eventloop when exit_now fires"""
462 451 if new:
463 452 loop = ioloop.IOLoop.instance()
464 453 loop.add_timeout(time.time()+0.1, loop.stop)
465 454
466 455 keepkernel_on_exit = None
467 456
468 457 # Over ZeroMQ, GUI control isn't done with PyOS_InputHook as there is no
469 458 # interactive input being read; we provide event loop support in ipkernel
470 459 from .eventloops import enable_gui
471 460 enable_gui = staticmethod(enable_gui)
472 461
473 462 def init_environment(self):
474 463 """Configure the user's environment.
475 464
476 465 """
477 466 env = os.environ
478 467 # These two ensure 'ls' produces nice coloring on BSD-derived systems
479 468 env['TERM'] = 'xterm-color'
480 469 env['CLICOLOR'] = '1'
481 470 # Since normal pagers don't work at all (over pexpect we don't have
482 471 # single-key control of the subprocess), try to disable paging in
483 472 # subprocesses as much as possible.
484 473 env['PAGER'] = 'cat'
485 474 env['GIT_PAGER'] = 'cat'
486 475
487 476 # And install the payload version of page.
488 477 install_payload_page()
489 478
490 479 def auto_rewrite_input(self, cmd):
491 480 """Called to show the auto-rewritten input for autocall and friends.
492 481
493 482 FIXME: this payload is currently not correctly processed by the
494 483 frontend.
495 484 """
496 485 new = self.prompt_manager.render('rewrite') + cmd
497 486 payload = dict(
498 487 source='IPython.zmq.zmqshell.ZMQInteractiveShell.auto_rewrite_input',
499 488 transformed_input=new,
500 489 )
501 490 self.payload_manager.write_payload(payload)
502 491
503 492 def ask_exit(self):
504 493 """Engage the exit actions."""
505 494 self.exit_now = True
506 495 payload = dict(
507 496 source='IPython.zmq.zmqshell.ZMQInteractiveShell.ask_exit',
508 497 exit=True,
509 498 keepkernel=self.keepkernel_on_exit,
510 499 )
511 500 self.payload_manager.write_payload(payload)
512 501
513 502 def _showtraceback(self, etype, evalue, stb):
514 503
515 504 exc_content = {
516 505 u'traceback' : stb,
517 506 u'ename' : unicode(etype.__name__),
518 507 u'evalue' : unicode(evalue)
519 508 }
520 509
521 510 dh = self.displayhook
522 511 # Send exception info over pub socket for other clients than the caller
523 512 # to pick up
524 513 topic = None
525 514 if dh.topic:
526 515 topic = dh.topic.replace(b'pyout', b'pyerr')
527 516
528 517 exc_msg = dh.session.send(dh.pub_socket, u'pyerr', json_clean(exc_content), dh.parent_header, ident=topic)
529 518
530 519 # FIXME - Hack: store exception info in shell object. Right now, the
531 520 # caller is reading this info after the fact, we need to fix this logic
532 521 # to remove this hack. Even uglier, we need to store the error status
533 522 # here, because in the main loop, the logic that sets it is being
534 523 # skipped because runlines swallows the exceptions.
535 524 exc_content[u'status'] = u'error'
536 525 self._reply_content = exc_content
537 526 # /FIXME
538 527
539 528 return exc_content
540 529
541 530 def set_next_input(self, text):
542 531 """Send the specified text to the frontend to be presented at the next
543 532 input cell."""
544 533 payload = dict(
545 534 source='IPython.zmq.zmqshell.ZMQInteractiveShell.set_next_input',
546 535 text=text
547 536 )
548 537 self.payload_manager.write_payload(payload)
549 538
550 539 #-------------------------------------------------------------------------
551 540 # Things related to magics
552 541 #-------------------------------------------------------------------------
553 542
554 543 def init_magics(self):
555 544 super(ZMQInteractiveShell, self).init_magics()
556 545 self.register_magics(KernelMagics)
557 546
558 547
559 548
560 549 InteractiveShellABC.register(ZMQInteractiveShell)
General Comments 0
You need to be logged in to leave comments. Login now