##// END OF EJS Templates
Manual update - Ville as maintainer.
fperez -
Show More
@@ -1,9373 +1,9373 b''
1 1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
2 2 \lyxformat 221
3 3 \textclass article
4 4 \begin_preamble
5 5 %\usepackage{ae,aecompl}
6 6 \usepackage{color}
7 7
8 8 % A few colors to replace the defaults for certain link types
9 9 \definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
10 10 \definecolor{darkorange}{rgb}{.71,0.21,0.01}
11 11 \definecolor{darkred}{rgb}{.52,0.08,0.01}
12 12 \definecolor{darkgreen}{rgb}{.12,.54,.11}
13 13
14 14 % Use and configure listings package for nicely formatted code
15 15 \usepackage{listings}
16 16 \lstset{
17 17 language=Python,
18 18 basicstyle=\small\ttfamily,
19 19 commentstyle=\ttfamily\color{blue},
20 20 stringstyle=\ttfamily\color{darkorange},
21 21 showstringspaces=false,
22 22 breaklines=true,
23 23 postbreak = \space\dots
24 24 }
25 25
26 26 \usepackage[%pdftex, % needed for pdflatex
27 27 breaklinks=true, % so long urls are correctly broken across lines
28 28 colorlinks=true,
29 29 urlcolor=blue,
30 30 linkcolor=darkred,
31 31 citecolor=darkgreen,
32 32 ]{hyperref}
33 33
34 34 \usepackage{html}
35 35
36 36 % This helps prevent overly long lines that stretch beyond the margins
37 37 \sloppy
38 38
39 39 % Define a \codelist command which either uses listings for latex, or
40 40 % plain verbatim for html (since latex2html doesn't understand the
41 41 % listings package).
42 42 \usepackage{verbatim}
43 43 \newcommand{\codelist}[1] {
44 44 \latex{\lstinputlisting{#1}}
45 45 \html{\verbatiminput{#1}}
46 46 }
47 47 \end_preamble
48 48 \language english
49 49 \inputencoding latin1
50 50 \fontscheme palatino
51 51 \graphics default
52 52 \paperfontsize 11
53 53 \spacing single
54 54 \papersize Default
55 55 \paperpackage a4
56 56 \use_geometry 1
57 57 \use_amsmath 0
58 58 \use_natbib 0
59 59 \use_numerical_citations 0
60 60 \paperorientation portrait
61 61 \leftmargin 1in
62 62 \topmargin 1in
63 63 \rightmargin 1in
64 64 \bottommargin 1in
65 65 \secnumdepth 3
66 66 \tocdepth 3
67 67 \paragraph_separation skip
68 68 \defskip medskip
69 69 \quotes_language english
70 70 \quotes_times 2
71 71 \papercolumns 1
72 72 \papersides 1
73 73 \paperpagestyle fancy
74 74
75 75 \layout Title
76 76
77 77 IPython
78 78 \newline
79 79
80 80 \size larger
81 81 An enhanced Interactive Python
82 82 \size large
83 83
84 84 \newline
85 85 User Manual, v.
86 86 __version__
87 87 \layout Author
88 88
89 89 Fernando P�rez
90 90 \layout Standard
91 91
92 92
93 93 \begin_inset ERT
94 94 status Collapsed
95 95
96 96 \layout Standard
97 97
98 98 \backslash
99 99 latex{
100 100 \end_inset
101 101
102 102
103 103 \begin_inset LatexCommand \tableofcontents{}
104 104
105 105 \end_inset
106 106
107 107
108 108 \begin_inset ERT
109 109 status Collapsed
110 110
111 111 \layout Standard
112 112 }
113 113 \end_inset
114 114
115 115
116 116 \layout Standard
117 117
118 118
119 119 \begin_inset ERT
120 120 status Open
121 121
122 122 \layout Standard
123 123
124 124 \backslash
125 125 html{
126 126 \backslash
127 127 bodytext{bgcolor=#ffffff}}
128 128 \end_inset
129 129
130 130
131 131 \layout Section
132 132 \pagebreak_top
133 133 Overview
134 134 \layout Standard
135 135
136 136 One of Python's most useful features is its interactive interpreter.
137 137 This system allows very fast testing of ideas without the overhead of creating
138 138 test files as is typical in most programming languages.
139 139 However, the interpreter supplied with the standard Python distribution
140 140 is somewhat limited for extended interactive use.
141 141 \layout Standard
142 142
143 143 IPython is a free software project (released under the BSD license) which
144 144 tries to:
145 145 \layout Enumerate
146 146
147 147 Provide an interactive shell superior to Python's default.
148 148 IPython has many features for object introspection, system shell access,
149 149 and its own special command system for adding functionality when working
150 150 interactively.
151 151 It tries to be a very efficient environment both for Python code development
152 152 and for exploration of problems using Python objects (in situations like
153 153 data analysis).
154 154 \layout Enumerate
155 155
156 156 Serve as an embeddable, ready to use interpreter for your own programs.
157 157 IPython can be started with a single call from inside another program,
158 158 providing access to the current namespace.
159 159 This can be very useful both for debugging purposes and for situations
160 160 where a blend of batch-processing and interactive exploration are needed.
161 161 \layout Enumerate
162 162
163 163 Offer a flexible framework which can be used as the base environment for
164 164 other systems with Python as the underlying language.
165 165 Specifically scientific environments like Mathematica, IDL and Matlab inspired
166 166 its design, but similar ideas can be useful in many fields.
167 167 \layout Enumerate
168 168
169 169 Allow interactive testing of threaded graphical toolkits.
170 170 IPython has support for interactive, non-blocking control of GTK, Qt and
171 171 WX applications via special threading flags.
172 172 The normal Python shell can only do this for Tkinter applications.
173 173 \layout Subsection
174 174
175 175 Main features
176 176 \layout Itemize
177 177
178 178 Dynamic object introspection.
179 179 One can access docstrings, function definition prototypes, source code,
180 180 source files and other details of any object accessible to the interpreter
181 181 with a single keystroke (`
182 182 \family typewriter
183 183 ?
184 184 \family default
185 185 ', and using `
186 186 \family typewriter
187 187 ??
188 188 \family default
189 189 ' provides additional detail).
190 190 \layout Itemize
191 191
192 192 Searching through modules and namespaces with `
193 193 \family typewriter
194 194 *
195 195 \family default
196 196 ' wildcards, both when using the `
197 197 \family typewriter
198 198 ?
199 199 \family default
200 200 ' system and via the
201 201 \family typewriter
202 202 %psearch
203 203 \family default
204 204 command.
205 205 \layout Itemize
206 206
207 207 Completion in the local namespace, by typing TAB at the prompt.
208 208 This works for keywords, methods, variables and files in the current directory.
209 209 This is supported via the readline library, and full access to configuring
210 210 readline's behavior is provided.
211 211 \layout Itemize
212 212
213 213 Numbered input/output prompts with command history (persistent across sessions
214 214 and tied to each profile), full searching in this history and caching of
215 215 all input and output.
216 216 \layout Itemize
217 217
218 218 User-extensible `magic' commands.
219 219 A set of commands prefixed with
220 220 \family typewriter
221 221 %
222 222 \family default
223 223 is available for controlling IPython itself and provides directory control,
224 224 namespace information and many aliases to common system shell commands.
225 225 \layout Itemize
226 226
227 227 Alias facility for defining your own system aliases.
228 228 \layout Itemize
229 229
230 230 Complete system shell access.
231 231 Lines starting with ! are passed directly to the system shell, and using
232 232 !! captures shell output into python variables for further use.
233 233 \layout Itemize
234 234
235 235 Background execution of Python commands in a separate thread.
236 236 IPython has an internal job manager called
237 237 \family typewriter
238 238 jobs
239 239 \family default
240 240 , and a conveninence backgrounding magic function called
241 241 \family typewriter
242 242 %bg
243 243 \family default
244 244 .
245 245 \layout Itemize
246 246
247 247 The ability to expand python variables when calling the system shell.
248 248 In a shell command, any python variable prefixed with
249 249 \family typewriter
250 250 $
251 251 \family default
252 252 is expanded.
253 253 A double
254 254 \family typewriter
255 255 $$
256 256 \family default
257 257 allows passing a literal
258 258 \family typewriter
259 259 $
260 260 \family default
261 261 to the shell (for access to shell and environment variables like
262 262 \family typewriter
263 263 $PATH
264 264 \family default
265 265 ).
266 266 \layout Itemize
267 267
268 268 Filesystem navigation, via a magic
269 269 \family typewriter
270 270 %cd
271 271 \family default
272 272 command, along with a persistent bookmark system (using
273 273 \family typewriter
274 274 %bookmark
275 275 \family default
276 276 ) for fast access to frequently visited directories.
277 277 \layout Itemize
278 278
279 279 A lightweight persistence framework via the
280 280 \family typewriter
281 281 %store
282 282 \family default
283 283 command, which allows you to save arbitrary Python variables.
284 284 These get restored automatically when your session restarts.
285 285 \layout Itemize
286 286
287 287 Automatic indentation (optional) of code as you type (through the readline
288 288 library).
289 289 \layout Itemize
290 290
291 291 Macro system for quickly re-executing multiple lines of previous input with
292 292 a single name.
293 293 Macros can be stored persistently via
294 294 \family typewriter
295 295 %store
296 296 \family default
297 297 and edited via
298 298 \family typewriter
299 299 %edit
300 300 \family default
301 301 .
302 302
303 303 \layout Itemize
304 304
305 305 Session logging (you can then later use these logs as code in your programs).
306 306 Logs can optionally timestamp all input, and also store session output
307 307 (marked as comments, so the log remains valid Python source code).
308 308 \layout Itemize
309 309
310 310 Session restoring: logs can be replayed to restore a previous session to
311 311 the state where you left it.
312 312 \layout Itemize
313 313
314 314 Verbose and colored exception traceback printouts.
315 315 Easier to parse visually, and in verbose mode they produce a lot of useful
316 316 debugging information (basically a terminal version of the cgitb module).
317 317 \layout Itemize
318 318
319 319 Auto-parentheses: callable objects can be executed without parentheses:
320 320
321 321 \family typewriter
322 322 `sin 3'
323 323 \family default
324 324 is automatically converted to
325 325 \family typewriter
326 326 `sin(3)
327 327 \family default
328 328 '.
329 329 \layout Itemize
330 330
331 331 Auto-quoting: using `
332 332 \family typewriter
333 333 ,
334 334 \family default
335 335 ' or `
336 336 \family typewriter
337 337 ;
338 338 \family default
339 339 ' as the first character forces auto-quoting of the rest of the line:
340 340 \family typewriter
341 341 `,my_function a\SpecialChar ~
342 342 b'
343 343 \family default
344 344 becomes automatically
345 345 \family typewriter
346 346 `my_function("a","b")'
347 347 \family default
348 348 , while
349 349 \family typewriter
350 350 `;my_function a\SpecialChar ~
351 351 b'
352 352 \family default
353 353 becomes
354 354 \family typewriter
355 355 `my_function("a b")'
356 356 \family default
357 357 .
358 358 \layout Itemize
359 359
360 360 Extensible input syntax.
361 361 You can define filters that pre-process user input to simplify input in
362 362 special situations.
363 363 This allows for example pasting multi-line code fragments which start with
364 364
365 365 \family typewriter
366 366 `>>>'
367 367 \family default
368 368 or
369 369 \family typewriter
370 370 `...'
371 371 \family default
372 372 such as those from other python sessions or the standard Python documentation.
373 373 \layout Itemize
374 374
375 375 Flexible configuration system.
376 376 It uses a configuration file which allows permanent setting of all command-line
377 377 options, module loading, code and file execution.
378 378 The system allows recursive file inclusion, so you can have a base file
379 379 with defaults and layers which load other customizations for particular
380 380 projects.
381 381 \layout Itemize
382 382
383 383 Embeddable.
384 384 You can call IPython as a python shell inside your own python programs.
385 385 This can be used both for debugging code or for providing interactive abilities
386 386 to your programs with knowledge about the local namespaces (very useful
387 387 in debugging and data analysis situations).
388 388 \layout Itemize
389 389
390 390 Easy debugger access.
391 391 You can set IPython to call up an enhanced version of the Python debugger
392 392 (
393 393 \family typewriter
394 394 pdb
395 395 \family default
396 396 ) every time there is an uncaught exception.
397 397 This drops you inside the code which triggered the exception with all the
398 398 data live and it is possible to navigate the stack to rapidly isolate the
399 399 source of a bug.
400 400 The
401 401 \family typewriter
402 402 %run
403 403 \family default
404 404 magic command --with the
405 405 \family typewriter
406 406 -d
407 407 \family default
408 408 option-- can run any script under
409 409 \family typewriter
410 410 pdb
411 411 \family default
412 412 's control, automatically setting initial breakpoints for you.
413 413 This version of
414 414 \family typewriter
415 415 pdb
416 416 \family default
417 417 has IPython-specific improvements, including tab-completion and traceback
418 418 coloring support.
419 419 \layout Itemize
420 420
421 421 Profiler support.
422 422 You can run single statements (similar to
423 423 \family typewriter
424 424 profile.run()
425 425 \family default
426 426 ) or complete programs under the profiler's control.
427 427 While this is possible with the standard
428 428 \family typewriter
429 429 profile
430 430 \family default
431 431 module, IPython wraps this functionality with magic commands (see
432 432 \family typewriter
433 433 `%prun'
434 434 \family default
435 435 and
436 436 \family typewriter
437 437 `%run -p
438 438 \family default
439 439 ') convenient for rapid interactive work.
440 440 \layout Subsection
441 441
442 442 Portability and Python requirements
443 443 \layout Standard
444 444
445 445
446 446 \series bold
447 447 Python requirements:
448 448 \series default
449 449 IPython requires with Python version 2.3 or newer.
450 450 If you are still using Python 2.2 and can not upgrade, the last version
451 451 of IPython which worked with Python 2.2 was 0.6.15, so you will have to use
452 452 that.
453 453 \layout Standard
454 454
455 455 IPython is developed under
456 456 \series bold
457 457 Linux
458 458 \series default
459 459 , but it should work in any reasonable Unix-type system (tested OK under
460 460 Solaris and the *BSD family, for which a port exists thanks to Dryice Liu).
461 461 \layout Standard
462 462
463 463
464 464 \series bold
465 465 Mac OS X
466 466 \series default
467 467 : it works, apparently without any problems (thanks to Jim Boyle at Lawrence
468 468 Livermore for the information).
469 469 Thanks to Andrea Riciputi, Fink support is available.
470 470 \layout Standard
471 471
472 472
473 473 \series bold
474 474 CygWin
475 475 \series default
476 476 : it works mostly OK, though some users have reported problems with prompt
477 477 coloring.
478 478 No satisfactory solution to this has been found so far, you may want to
479 479 disable colors permanently in the
480 480 \family typewriter
481 481 ipythonrc
482 482 \family default
483 483 configuration file if you experience problems.
484 484 If you have proper color support under cygwin, please post to the IPython
485 485 mailing list so this issue can be resolved for all users.
486 486 \layout Standard
487 487
488 488
489 489 \series bold
490 490 Windows
491 491 \series default
492 492 : it works well under Windows XP/2k, and I suspect NT should behave similarly.
493 493 Section\SpecialChar ~
494 494
495 495 \begin_inset LatexCommand \ref{sub:Under-Windows}
496 496
497 497 \end_inset
498 498
499 499 describes installation details for Windows, including some additional tools
500 500 needed on this platform.
501 501 \layout Standard
502 502
503 503 Windows 9x support is present, and has been reported to work fine (at least
504 504 on WinME).
505 505 \layout Standard
506 506
507 507 Note, that I have very little access to and experience with Windows development.
508 508 However, an excellent group of Win32 users (led by Ville Vainio), consistenly
509 509 contribute bugfixes and platform-specific enhancements, so they more than
510 510 make up for my deficiencies on that front.
511 511 In fact, Win32 users report using IPython as a system shell (see Sec.\SpecialChar ~
512 512
513 513 \begin_inset LatexCommand \ref{sec:IPython-as-shell}
514 514
515 515 \end_inset
516 516
517 517 for details), as it offers a level of control and features which the default
518 518
519 519 \family typewriter
520 520 cmd.exe
521 521 \family default
522 522 doesn't provide.
523 523 \layout Subsection
524 524
525 525 Location
526 526 \layout Standard
527 527
528 528 IPython is generously hosted at
529 529 \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
530 530
531 531 \end_inset
532 532
533 533 by the Enthought, Inc and the SciPy project.
534 534 This site offers downloads, subversion access, mailing lists and a bug
535 535 tracking system.
536 536 I am very grateful to Enthought (
537 537 \begin_inset LatexCommand \htmlurl{http://www.enthought.com}
538 538
539 539 \end_inset
540 540
541 541 ) and all of the SciPy team for their contribution.
542 542 \layout Section
543 543
544 544
545 545 \begin_inset LatexCommand \label{sec:install}
546 546
547 547 \end_inset
548 548
549 549 Installation
550 550 \layout Subsection
551 551
552 552 Instant instructions
553 553 \layout Standard
554 554
555 555 If you are of the impatient kind, under Linux/Unix simply untar/unzip the
556 556 download, then install with
557 557 \family typewriter
558 558 `python setup.py install'
559 559 \family default
560 560 .
561 561 Under Windows, double-click on the provided
562 562 \family typewriter
563 563 .exe
564 564 \family default
565 565 binary installer.
566 566 \layout Standard
567 567
568 568 Then, take a look at Sections
569 569 \begin_inset LatexCommand \ref{sec:good_config}
570 570
571 571 \end_inset
572 572
573 573 for configuring things optimally and
574 574 \begin_inset LatexCommand \ref{sec:quick_tips}
575 575
576 576 \end_inset
577 577
578 578 for quick tips on efficient use of IPython.
579 579 You can later refer to the rest of the manual for all the gory details.
580 580 \layout Standard
581 581
582 582 See the notes in sec.
583 583
584 584 \begin_inset LatexCommand \ref{sec:upgrade}
585 585
586 586 \end_inset
587 587
588 588 for upgrading IPython versions.
589 589 \layout Subsection
590 590
591 591 Detailed Unix instructions (Linux, Mac OS X, etc.)
592 592 \layout Standard
593 593
594 594 For RPM based systems, simply install the supplied package in the usual
595 595 manner.
596 596 If you download the tar archive, the process is:
597 597 \layout Enumerate
598 598
599 599 Unzip/untar the
600 600 \family typewriter
601 601 ipython-XXX.tar.gz
602 602 \family default
603 603 file wherever you want (
604 604 \family typewriter
605 605 XXX
606 606 \family default
607 607 is the version number).
608 608 It will make a directory called
609 609 \family typewriter
610 610 ipython-XXX.
611 611
612 612 \family default
613 613 Change into that directory where you will find the files
614 614 \family typewriter
615 615 README
616 616 \family default
617 617 and
618 618 \family typewriter
619 619 setup.py
620 620 \family default
621 621 .
622 622
623 623 \family typewriter
624 624 O
625 625 \family default
626 626 nce you've completed the installation, you can safely remove this directory.
627 627
628 628 \layout Enumerate
629 629
630 630 If you are installing over a previous installation of version 0.2.0 or earlier,
631 631 first remove your
632 632 \family typewriter
633 633 $HOME/.ipython
634 634 \family default
635 635 directory, since the configuration file format has changed somewhat (the
636 636 '=' were removed from all option specifications).
637 637 Or you can call ipython with the
638 638 \family typewriter
639 639 -upgrade
640 640 \family default
641 641 option and it will do this automatically for you.
642 642 \layout Enumerate
643 643
644 644 IPython uses distutils, so you can install it by simply typing at the system
645 645 prompt (don't type the
646 646 \family typewriter
647 647 $
648 648 \family default
649 649 )
650 650 \newline
651 651
652 652 \family typewriter
653 653 $ python setup.py install
654 654 \family default
655 655
656 656 \newline
657 657 Note that this assumes you have root access to your machine.
658 658 If you don't have root access or don't want IPython to go in the default
659 659 python directories, you'll need to use the
660 660 \begin_inset ERT
661 661 status Collapsed
662 662
663 663 \layout Standard
664 664
665 665 \backslash
666 666 verb|--home|
667 667 \end_inset
668 668
669 669 option (or
670 670 \begin_inset ERT
671 671 status Collapsed
672 672
673 673 \layout Standard
674 674
675 675 \backslash
676 676 verb|--prefix|
677 677 \end_inset
678 678
679 679 ).
680 680 For example:
681 681 \newline
682 682
683 683 \begin_inset ERT
684 684 status Collapsed
685 685
686 686 \layout Standard
687 687
688 688 \backslash
689 689 verb|$ python setup.py install --home $HOME/local|
690 690 \end_inset
691 691
692 692
693 693 \newline
694 694 will install IPython into
695 695 \family typewriter
696 696 $HOME/local
697 697 \family default
698 698 and its subdirectories (creating them if necessary).
699 699 \newline
700 700 You can type
701 701 \newline
702 702
703 703 \begin_inset ERT
704 704 status Collapsed
705 705
706 706 \layout Standard
707 707
708 708 \backslash
709 709 verb|$ python setup.py --help|
710 710 \end_inset
711 711
712 712
713 713 \newline
714 714 for more details.
715 715 \newline
716 716 Note that if you change the default location for
717 717 \begin_inset ERT
718 718 status Collapsed
719 719
720 720 \layout Standard
721 721
722 722 \backslash
723 723 verb|--home|
724 724 \end_inset
725 725
726 726 at installation, IPython may end up installed at a location which is not
727 727 part of your
728 728 \family typewriter
729 729 $PYTHONPATH
730 730 \family default
731 731 environment variable.
732 732 In this case, you'll need to configure this variable to include the actual
733 733 directory where the
734 734 \family typewriter
735 735 IPython/
736 736 \family default
737 737 directory ended (typically the value you give to
738 738 \begin_inset ERT
739 739 status Collapsed
740 740
741 741 \layout Standard
742 742
743 743 \backslash
744 744 verb|--home|
745 745 \end_inset
746 746
747 747 plus
748 748 \family typewriter
749 749 /lib/python
750 750 \family default
751 751 ).
752 752 \layout Subsubsection
753 753
754 754 Mac OSX information
755 755 \layout Standard
756 756
757 757 Under OSX, there is a choice you need to make.
758 758 Apple ships its own build of Python, which lives in the core OSX filesystem
759 759 hierarchy.
760 760 You can also manually install a separate Python, either purely by hand
761 761 (typically in
762 762 \family typewriter
763 763 /usr/local
764 764 \family default
765 765 ) or by using Fink, which puts everything under
766 766 \family typewriter
767 767 /sw
768 768 \family default
769 769 .
770 770 Which route to follow is a matter of personal preference, as I've seen
771 771 users who favor each of the approaches.
772 772 Here I will simply list the known installation issues under OSX, along
773 773 with their solutions.
774 774 \layout Standard
775 775
776 776 This page:
777 777 \begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html}
778 778
779 779 \end_inset
780 780
781 781 contains information on this topic, with additional details on how to make
782 782 IPython and matplotlib play nicely under OSX.
783 783 \layout Subsubsection*
784 784
785 785 GUI problems
786 786 \layout Standard
787 787
788 788 The following instructions apply to an install of IPython under OSX from
789 789 unpacking the
790 790 \family typewriter
791 791 .tar.gz
792 792 \family default
793 793 distribution and installing it for the default Python interpreter shipped
794 794 by Apple.
795 795 If you are using a fink install, fink will take care of these details for
796 796 you, by installing IPython against fink's Python.
797 797 \layout Standard
798 798
799 799 IPython offers various forms of support for interacting with graphical applicati
800 800 ons from the command line, from simple Tk apps (which are in principle always
801 801 supported by Python) to interactive control of WX, Qt and GTK apps.
802 802 Under OSX, however, this requires that ipython is installed by calling
803 803 the special
804 804 \family typewriter
805 805 pythonw
806 806 \family default
807 807 script at installation time, which takes care of coordinating things with
808 808 Apple's graphical environment.
809 809 \layout Standard
810 810
811 811 So when installing under OSX, it is best to use the following command:
812 812 \family typewriter
813 813
814 814 \newline
815 815
816 816 \family default
817 817
818 818 \begin_inset ERT
819 819 status Collapsed
820 820
821 821 \layout Standard
822 822
823 823 \backslash
824 824 verb| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
825 825 \end_inset
826 826
827 827
828 828 \newline
829 829 or
830 830 \newline
831 831
832 832 \begin_inset ERT
833 833 status Collapsed
834 834
835 835 \layout Standard
836 836
837 837 \backslash
838 838 verb| $ sudo pythonw setup.py install --install-scripts=/usr/bin|
839 839 \end_inset
840 840
841 841
842 842 \newline
843 843 depending on where you like to keep hand-installed executables.
844 844 \layout Standard
845 845
846 846 The resulting script will have an appropriate shebang line (the first line
847 847 in the script whic begins with
848 848 \family typewriter
849 849 #!...
850 850 \family default
851 851 ) such that the ipython interpreter can interact with the OS X GUI.
852 852 If the installed version does not work and has a shebang line that points
853 853 to, for example, just
854 854 \family typewriter
855 855 /usr/bin/python
856 856 \family default
857 857 , then you might have a stale, cached version in your
858 858 \family typewriter
859 859 build/scripts-<python-version>
860 860 \family default
861 861 directory.
862 862 Delete that directory and rerun the
863 863 \family typewriter
864 864 setup.py
865 865 \family default
866 866 .
867 867
868 868 \layout Standard
869 869
870 870 It is also a good idea to use the special flag
871 871 \begin_inset ERT
872 872 status Collapsed
873 873
874 874 \layout Standard
875 875
876 876 \backslash
877 877 verb|--install-scripts|
878 878 \end_inset
879 879
880 880 as indicated above, to ensure that the ipython scripts end up in a location
881 881 which is part of your
882 882 \family typewriter
883 883 $PATH
884 884 \family default
885 885 .
886 886 Otherwise Apple's Python will put the scripts in an internal directory
887 887 not available by default at the command line (if you use
888 888 \family typewriter
889 889 /usr/local/bin
890 890 \family default
891 891 , you need to make sure this is in your
892 892 \family typewriter
893 893 $PATH
894 894 \family default
895 895 , which may not be true by default).
896 896 \layout Subsubsection*
897 897
898 898 Readline problems
899 899 \layout Standard
900 900
901 901 By default, the Python version shipped by Apple does
902 902 \emph on
903 903 not
904 904 \emph default
905 905 include the readline library, so central to IPython's behavior.
906 906 If you install IPython against Apple's Python, you will not have arrow
907 907 keys, tab completion, etc.
908 908 For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here:
909 909 \newline
910 910
911 911 \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip}
912 912
913 913 \end_inset
914 914
915 915
916 916 \layout Standard
917 917
918 918 If you are using OSX 10.4 (Tiger), after installing this package you need
919 919 to either:
920 920 \layout Enumerate
921 921
922 922 move
923 923 \family typewriter
924 924 readline.so
925 925 \family default
926 926 from
927 927 \family typewriter
928 928 /Library/Python/2.3
929 929 \family default
930 930 to
931 931 \family typewriter
932 932 /Library/Python/2.3/site-packages
933 933 \family default
934 934 , or
935 935 \layout Enumerate
936 936
937 937 install
938 938 \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip}
939 939
940 940 \end_inset
941 941
942 942
943 943 \layout Standard
944 944
945 945 Users installing against Fink's Python or a properly hand-built one should
946 946 not have this problem.
947 947 \layout Subsubsection*
948 948
949 949 DarwinPorts
950 950 \layout Standard
951 951
952 952 I report here a message from an OSX user, who suggests an alternative means
953 953 of using IPython under this operating system with good results.
954 954 Please let me know of any updates that may be useful for this section.
955 955 His message is reproduced verbatim below:
956 956 \layout Quote
957 957
958 958 From: Markus Banfi
959 959 \family typewriter
960 960 <markus.banfi-AT-mospheira.net>
961 961 \layout Quote
962 962
963 963 As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead
964 964 of Fink.
965 965 I had no problems installing ipython with DarwinPorts.
966 966 It's just:
967 967 \layout Quote
968 968
969 969
970 970 \family typewriter
971 971 sudo port install py-ipython
972 972 \layout Quote
973 973
974 974 It automatically resolved all dependencies (python24, readline, py-readline).
975 975 So far I did not encounter any problems with the DarwinPorts port of ipython.
976 976
977 977 \layout Subsection
978 978
979 979
980 980 \begin_inset LatexCommand \label{sub:Under-Windows}
981 981
982 982 \end_inset
983 983
984 984 Windows instructions
985 985 \layout Standard
986 986
987 987 Some of IPython's very useful features are:
988 988 \layout Itemize
989 989
990 990 Integrated readline support (Tab-based file, object and attribute completion,
991 991 input history across sessions, editable command line, etc.)
992 992 \layout Itemize
993 993
994 994 Coloring of prompts, code and tracebacks.
995 995 \layout Standard
996 996
997 997 These, by default, are only available under Unix-like operating systems.
998 998 However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit
999 999 from them.
1000 1000 His readline library implements both GNU readline functionality and color
1001 1001 support, so that IPython under Windows XP/2k can be as friendly and powerful
1002 1002 as under Unix-like environments.
1003 1003 \layout Standard
1004 1004
1005 1005 The
1006 1006 \family typewriter
1007 1007 readline
1008 1008 \family default
1009 1009 extension needs two other libraries to work, so in all you need:
1010 1010 \layout Enumerate
1011 1011
1012 1012
1013 1013 \family typewriter
1014 1014 PyWin32
1015 1015 \family default
1016 1016 from
1017 1017 \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/mhammond}
1018 1018
1019 1019 \end_inset
1020 1020
1021 1021 .
1022 1022 \layout Enumerate
1023 1023
1024 1024
1025 1025 \family typewriter
1026 1026 CTypes
1027 1027 \family default
1028 1028 from
1029 1029 \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes}
1030 1030
1031 1031 \end_inset
1032 1032
1033 1033 (you
1034 1034 \emph on
1035 1035 must
1036 1036 \emph default
1037 1037 use version 0.9.1 or newer).
1038 1038 \layout Enumerate
1039 1039
1040 1040
1041 1041 \family typewriter
1042 1042 Readline
1043 1043 \family default
1044 1044 for Windows from
1045 1045 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/uncpythontools}
1046 1046
1047 1047 \end_inset
1048 1048
1049 1049 .
1050 1050 \layout Standard
1051 1051
1052 1052
1053 1053 \series bold
1054 1054 Warning about a broken readline-like library:
1055 1055 \series default
1056 1056 several users have reported problems stemming from using the pseudo-readline
1057 1057 library at
1058 1058 \begin_inset LatexCommand \htmlurl{http://newcenturycomputers.net/projects/readline.html}
1059 1059
1060 1060 \end_inset
1061 1061
1062 1062 .
1063 1063 This is a broken library which, while called readline, only implements
1064 1064 an incomplete subset of the readline API.
1065 1065 Since it is still called readline, it fools IPython's detection mechanisms
1066 1066 and causes unpredictable crashes later.
1067 1067 If you wish to use IPython under Windows, you must NOT use this library,
1068 1068 which for all purposes is (at least as of version 1.6) terminally broken.
1069 1069 \layout Subsubsection
1070 1070
1071 1071 Installation procedure
1072 1072 \layout Standard
1073 1073
1074 1074 Once you have the above installed, from the IPython download directory grab
1075 1075 the
1076 1076 \family typewriter
1077 1077 ipython-XXX.win32.exe
1078 1078 \family default
1079 1079 file, where
1080 1080 \family typewriter
1081 1081 XXX
1082 1082 \family default
1083 1083 represents the version number.
1084 1084 This is a regular windows executable installer, which you can simply double-cli
1085 1085 ck to install.
1086 1086 It will add an entry for IPython to your Start Menu, as well as registering
1087 1087 IPython in the Windows list of applications, so you can later uninstall
1088 1088 it from the Control Panel.
1089 1089
1090 1090 \layout Standard
1091 1091
1092 1092 IPython tries to install the configuration information in a directory named
1093 1093
1094 1094 \family typewriter
1095 1095 .ipython
1096 1096 \family default
1097 1097 (
1098 1098 \family typewriter
1099 1099 _ipython
1100 1100 \family default
1101 1101 under Windows) located in your `home' directory.
1102 1102 IPython sets this directory by looking for a
1103 1103 \family typewriter
1104 1104 HOME
1105 1105 \family default
1106 1106 environment variable; if such a variable does not exist, it uses
1107 1107 \family typewriter
1108 1108 HOMEDRIVE
1109 1109 \backslash
1110 1110 HOMEPATH
1111 1111 \family default
1112 1112 (these are always defined by Windows).
1113 1113 This typically gives something like
1114 1114 \family typewriter
1115 1115 C:
1116 1116 \backslash
1117 1117 Documents and Settings
1118 1118 \backslash
1119 1119 YourUserName
1120 1120 \family default
1121 1121 , but your local details may vary.
1122 1122 In this directory you will find all the files that configure IPython's
1123 1123 defaults, and you can put there your profiles and extensions.
1124 1124 This directory is automatically added by IPython to
1125 1125 \family typewriter
1126 1126 sys.path
1127 1127 \family default
1128 1128 , so anything you place there can be found by
1129 1129 \family typewriter
1130 1130 import
1131 1131 \family default
1132 1132 statements.
1133 1133 \layout Paragraph
1134 1134
1135 1135 Upgrading
1136 1136 \layout Standard
1137 1137
1138 1138 For an IPython upgrade, you should first uninstall the previous version.
1139 1139 This will ensure that all files and directories (such as the documentation)
1140 1140 which carry embedded version strings in their names are properly removed.
1141 1141 \layout Paragraph
1142 1142
1143 1143 Manual installation under Win32
1144 1144 \layout Standard
1145 1145
1146 1146 In case the automatic installer does not work for some reason, you can download
1147 1147 the
1148 1148 \family typewriter
1149 1149 ipython-XXX.tar.gz
1150 1150 \family default
1151 1151 file, which contains the full IPython source distribution (the popular
1152 1152 WinZip can read
1153 1153 \family typewriter
1154 1154 .tar.gz
1155 1155 \family default
1156 1156 files).
1157 1157 After uncompressing the archive, you can install it at a command terminal
1158 1158 just like any other Python module, by using
1159 1159 \family typewriter
1160 1160 `python setup.py install'
1161 1161 \family default
1162 1162 .
1163 1163
1164 1164 \layout Standard
1165 1165
1166 1166 After the installation, run the supplied
1167 1167 \family typewriter
1168 1168 win32_manual_post_install.py
1169 1169 \family default
1170 1170 script, which creates the necessary Start Menu shortcuts for you.
1171 1171 \layout Subsection
1172 1172
1173 1173
1174 1174 \begin_inset LatexCommand \label{sec:upgrade}
1175 1175
1176 1176 \end_inset
1177 1177
1178 1178 Upgrading from a previous version
1179 1179 \layout Standard
1180 1180
1181 1181 If you are upgrading from a previous version of IPython, after doing the
1182 1182 routine installation described above, you should call IPython with the
1183 1183
1184 1184 \family typewriter
1185 1185 -upgrade
1186 1186 \family default
1187 1187 option the first time you run your new copy.
1188 1188 This will automatically update your configuration directory while preserving
1189 1189 copies of your old files.
1190 1190 You can then later merge back any personal customizations you may have
1191 1191 made into the new files.
1192 1192 It is a good idea to do this as there may be new options available in the
1193 1193 new configuration files which you will not have.
1194 1194 \layout Standard
1195 1195
1196 1196 Under Windows, if you don't know how to call python scripts with arguments
1197 1197 from a command line, simply delete the old config directory and IPython
1198 1198 will make a new one.
1199 1199 Win2k and WinXP users will find it in
1200 1200 \family typewriter
1201 1201 C:
1202 1202 \backslash
1203 1203 Documents and Settings
1204 1204 \backslash
1205 1205 YourUserName
1206 1206 \backslash
1207 1207 _ipython
1208 1208 \family default
1209 1209 , and Win 9x users under
1210 1210 \family typewriter
1211 1211 C:
1212 1212 \backslash
1213 1213 Program Files
1214 1214 \backslash
1215 1215 IPython
1216 1216 \backslash
1217 1217 _ipython.
1218 1218 \layout Section
1219 1219
1220 1220
1221 1221 \begin_inset LatexCommand \label{sec:good_config}
1222 1222
1223 1223 \end_inset
1224 1224
1225 1225
1226 1226 \begin_inset OptArg
1227 1227 collapsed true
1228 1228
1229 1229 \layout Standard
1230 1230
1231 1231 Initial configuration
1232 1232 \begin_inset ERT
1233 1233 status Collapsed
1234 1234
1235 1235 \layout Standard
1236 1236
1237 1237 \backslash
1238 1238 ldots
1239 1239 \end_inset
1240 1240
1241 1241
1242 1242 \end_inset
1243 1243
1244 1244 Initial configuration of your environment
1245 1245 \layout Standard
1246 1246
1247 1247 This section will help you set various things in your environment for your
1248 1248 IPython sessions to be as efficient as possible.
1249 1249 All of IPython's configuration information, along with several example
1250 1250 files, is stored in a directory named by default
1251 1251 \family typewriter
1252 1252 $HOME/.ipython
1253 1253 \family default
1254 1254 .
1255 1255 You can change this by defining the environment variable
1256 1256 \family typewriter
1257 1257 IPYTHONDIR
1258 1258 \family default
1259 1259 , or at runtime with the command line option
1260 1260 \family typewriter
1261 1261 -ipythondir
1262 1262 \family default
1263 1263 .
1264 1264 \layout Standard
1265 1265
1266 1266 If all goes well, the first time you run IPython it should automatically
1267 1267 create a user copy of the config directory for you, based on its builtin
1268 1268 defaults.
1269 1269 You can look at the files it creates to learn more about configuring the
1270 1270 system.
1271 1271 The main file you will modify to configure IPython's behavior is called
1272 1272
1273 1273 \family typewriter
1274 1274 ipythonrc
1275 1275 \family default
1276 1276 (with a
1277 1277 \family typewriter
1278 1278 .ini
1279 1279 \family default
1280 1280 extension under Windows), included for reference in Sec.
1281 1281
1282 1282 \begin_inset LatexCommand \ref{sec:ipytonrc-sample}
1283 1283
1284 1284 \end_inset
1285 1285
1286 1286 .
1287 1287 This file is very commented and has many variables you can change to suit
1288 1288 your taste, you can find more details in Sec.
1289 1289
1290 1290 \begin_inset LatexCommand \ref{sec:customization}
1291 1291
1292 1292 \end_inset
1293 1293
1294 1294 .
1295 1295 Here we discuss the basic things you will want to make sure things are
1296 1296 working properly from the beginning.
1297 1297 \layout Subsection
1298 1298
1299 1299
1300 1300 \begin_inset LatexCommand \label{sec:help-access}
1301 1301
1302 1302 \end_inset
1303 1303
1304 1304 Access to the Python help system
1305 1305 \layout Standard
1306 1306
1307 1307 This is true for Python in general (not just for IPython): you should have
1308 1308 an environment variable called
1309 1309 \family typewriter
1310 1310 PYTHONDOCS
1311 1311 \family default
1312 1312 pointing to the directory where your HTML Python documentation lives.
1313 1313 In my system it's
1314 1314 \family typewriter
1315 1315 /usr/share/doc/python-docs-2.3.4/html
1316 1316 \family default
1317 1317 , check your local details or ask your systems administrator.
1318 1318
1319 1319 \layout Standard
1320 1320
1321 1321 This is the directory which holds the HTML version of the Python manuals.
1322 1322 Unfortunately it seems that different Linux distributions package these
1323 1323 files differently, so you may have to look around a bit.
1324 1324 Below I show the contents of this directory on my system for reference:
1325 1325 \layout Standard
1326 1326
1327 1327
1328 1328 \family typewriter
1329 1329 [html]> ls
1330 1330 \newline
1331 1331 about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat tut/
1332 1332 about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
1333 1333 \layout Standard
1334 1334
1335 1335 You should really make sure this variable is correctly set so that Python's
1336 1336 pydoc-based help system works.
1337 1337 It is a powerful and convenient system with full access to the Python manuals
1338 1338 and all modules accessible to you.
1339 1339 \layout Standard
1340 1340
1341 1341 Under Windows it seems that pydoc finds the documentation automatically,
1342 1342 so no extra setup appears necessary.
1343 1343 \layout Subsection
1344 1344
1345 1345 Editor
1346 1346 \layout Standard
1347 1347
1348 1348 The
1349 1349 \family typewriter
1350 1350 %edit
1351 1351 \family default
1352 1352 command (and its alias
1353 1353 \family typewriter
1354 1354 %ed
1355 1355 \family default
1356 1356 ) will invoke the editor set in your environment as
1357 1357 \family typewriter
1358 1358 EDITOR
1359 1359 \family default
1360 1360 .
1361 1361 If this variable is not set, it will default to
1362 1362 \family typewriter
1363 1363 vi
1364 1364 \family default
1365 1365 under Linux/Unix and to
1366 1366 \family typewriter
1367 1367 notepad
1368 1368 \family default
1369 1369 under Windows.
1370 1370 You may want to set this variable properly and to a lightweight editor
1371 1371 which doesn't take too long to start (that is, something other than a new
1372 1372 instance of
1373 1373 \family typewriter
1374 1374 Emacs
1375 1375 \family default
1376 1376 ).
1377 1377 This way you can edit multi-line code quickly and with the power of a real
1378 1378 editor right inside IPython.
1379 1379
1380 1380 \layout Standard
1381 1381
1382 1382 If you are a dedicated
1383 1383 \family typewriter
1384 1384 Emacs
1385 1385 \family default
1386 1386 user, you should set up the
1387 1387 \family typewriter
1388 1388 Emacs
1389 1389 \family default
1390 1390 server so that new requests are handled by the original process.
1391 1391 This means that almost no time is spent in handling the request (assuming
1392 1392 an
1393 1393 \family typewriter
1394 1394 Emacs
1395 1395 \family default
1396 1396 process is already running).
1397 1397 For this to work, you need to set your
1398 1398 \family typewriter
1399 1399 EDITOR
1400 1400 \family default
1401 1401 environment variable to
1402 1402 \family typewriter
1403 1403 'emacsclient'
1404 1404 \family default
1405 1405 .
1406 1406
1407 1407 \family typewriter
1408 1408
1409 1409 \family default
1410 1410 The code below, supplied by Francois Pinard, can then be used in your
1411 1411 \family typewriter
1412 1412 .emacs
1413 1413 \family default
1414 1414 file to enable the server:
1415 1415 \layout Standard
1416 1416
1417 1417
1418 1418 \family typewriter
1419 1419 (defvar server-buffer-clients)
1420 1420 \newline
1421 1421 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
1422 1422 \newline
1423 1423
1424 1424 \begin_inset ERT
1425 1425 status Collapsed
1426 1426
1427 1427 \layout Standard
1428 1428
1429 1429 \backslash
1430 1430 hspace*{0mm}
1431 1431 \end_inset
1432 1432
1433 1433 \SpecialChar ~
1434 1434 \SpecialChar ~
1435 1435 (server-start)
1436 1436 \newline
1437 1437
1438 1438 \begin_inset ERT
1439 1439 status Collapsed
1440 1440
1441 1441 \layout Standard
1442 1442
1443 1443 \backslash
1444 1444 hspace*{0mm}
1445 1445 \end_inset
1446 1446
1447 1447 \SpecialChar ~
1448 1448 \SpecialChar ~
1449 1449 (defun fp-kill-server-with-buffer-routine ()
1450 1450 \newline
1451 1451
1452 1452 \begin_inset ERT
1453 1453 status Collapsed
1454 1454
1455 1455 \layout Standard
1456 1456
1457 1457 \backslash
1458 1458 hspace*{0mm}
1459 1459 \end_inset
1460 1460
1461 1461 \SpecialChar ~
1462 1462 \SpecialChar ~
1463 1463 \SpecialChar ~
1464 1464 \SpecialChar ~
1465 1465 (and server-buffer-clients (server-done)))
1466 1466 \newline
1467 1467
1468 1468 \begin_inset ERT
1469 1469 status Collapsed
1470 1470
1471 1471 \layout Standard
1472 1472
1473 1473 \backslash
1474 1474 hspace*{0mm}
1475 1475 \end_inset
1476 1476
1477 1477 \SpecialChar ~
1478 1478 \SpecialChar ~
1479 1479 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
1480 1480 \layout Standard
1481 1481
1482 1482 You can also set the value of this editor via the commmand-line option '-
1483 1483 \family typewriter
1484 1484 editor'
1485 1485 \family default
1486 1486 or in your
1487 1487 \family typewriter
1488 1488 ipythonrc
1489 1489 \family default
1490 1490 file.
1491 1491 This is useful if you wish to use specifically for IPython an editor different
1492 1492 from your typical default (and for Windows users who tend to use fewer
1493 1493 environment variables).
1494 1494 \layout Subsection
1495 1495
1496 1496 Color
1497 1497 \layout Standard
1498 1498
1499 1499 The default IPython configuration has most bells and whistles turned on
1500 1500 (they're pretty safe).
1501 1501 But there's one that
1502 1502 \emph on
1503 1503 may
1504 1504 \emph default
1505 1505 cause problems on some systems: the use of color on screen for displaying
1506 1506 information.
1507 1507 This is very useful, since IPython can show prompts and exception tracebacks
1508 1508 with various colors, display syntax-highlighted source code, and in general
1509 1509 make it easier to visually parse information.
1510 1510 \layout Standard
1511 1511
1512 1512 The following terminals seem to handle the color sequences fine:
1513 1513 \layout Itemize
1514 1514
1515 1515 Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm.
1516 1516 \layout Itemize
1517 1517
1518 1518 CDE terminal (tested under Solaris).
1519 1519 This one boldfaces light colors.
1520 1520 \layout Itemize
1521 1521
1522 1522 (X)Emacs buffers.
1523 1523 See sec.
1524 1524 \begin_inset LatexCommand \ref{sec:emacs}
1525 1525
1526 1526 \end_inset
1527 1527
1528 1528 for more details on using IPython with (X)Emacs.
1529 1529 \layout Itemize
1530 1530
1531 1531 A Windows (XP/2k) command prompt
1532 1532 \emph on
1533 1533 with Gary Bishop's support extensions
1534 1534 \emph default
1535 1535 .
1536 1536 Gary's extensions are discussed in Sec.\SpecialChar ~
1537 1537
1538 1538 \begin_inset LatexCommand \ref{sub:Under-Windows}
1539 1539
1540 1540 \end_inset
1541 1541
1542 1542 .
1543 1543 \layout Itemize
1544 1544
1545 1545 A Windows (XP/2k) CygWin shell.
1546 1546 Although some users have reported problems; it is not clear whether there
1547 1547 is an issue for everyone or only under specific configurations.
1548 1548 If you have full color support under cygwin, please post to the IPython
1549 1549 mailing list so this issue can be resolved for all users.
1550 1550 \layout Standard
1551 1551
1552 1552 These have shown problems:
1553 1553 \layout Itemize
1554 1554
1555 1555 Windows command prompt in WinXP/2k logged into a Linux machine via telnet
1556 1556 or ssh.
1557 1557 \layout Itemize
1558 1558
1559 1559 Windows native command prompt in WinXP/2k,
1560 1560 \emph on
1561 1561 without
1562 1562 \emph default
1563 1563 Gary Bishop's extensions.
1564 1564 Once Gary's readline library is installed, the normal WinXP/2k command
1565 1565 prompt works perfectly.
1566 1566 \layout Standard
1567 1567
1568 1568 Currently the following color schemes are available:
1569 1569 \layout Itemize
1570 1570
1571 1571
1572 1572 \family typewriter
1573 1573 NoColor
1574 1574 \family default
1575 1575 : uses no color escapes at all (all escapes are empty
1576 1576 \begin_inset Quotes eld
1577 1577 \end_inset
1578 1578
1579 1579
1580 1580 \begin_inset Quotes eld
1581 1581 \end_inset
1582 1582
1583 1583 strings).
1584 1584 This 'scheme' is thus fully safe to use in any terminal.
1585 1585 \layout Itemize
1586 1586
1587 1587
1588 1588 \family typewriter
1589 1589 Linux
1590 1590 \family default
1591 1591 : works well in Linux console type environments: dark background with light
1592 1592 fonts.
1593 1593 It uses bright colors for information, so it is difficult to read if you
1594 1594 have a light colored background.
1595 1595 \layout Itemize
1596 1596
1597 1597
1598 1598 \family typewriter
1599 1599 LightBG
1600 1600 \family default
1601 1601 : the basic colors are similar to those in the
1602 1602 \family typewriter
1603 1603 Linux
1604 1604 \family default
1605 1605 scheme but darker.
1606 1606 It is easy to read in terminals with light backgrounds.
1607 1607 \layout Standard
1608 1608
1609 1609 IPython uses colors for two main groups of things: prompts and tracebacks
1610 1610 which are directly printed to the terminal, and the object introspection
1611 1611 system which passes large sets of data through a pager.
1612 1612 \layout Subsubsection
1613 1613
1614 1614 Input/Output prompts and exception tracebacks
1615 1615 \layout Standard
1616 1616
1617 1617 You can test whether the colored prompts and tracebacks work on your system
1618 1618 interactively by typing
1619 1619 \family typewriter
1620 1620 '%colors Linux'
1621 1621 \family default
1622 1622 at the prompt (use '
1623 1623 \family typewriter
1624 1624 %colors LightBG'
1625 1625 \family default
1626 1626 if your terminal has a light background).
1627 1627 If the input prompt shows garbage like:
1628 1628 \newline
1629 1629
1630 1630 \family typewriter
1631 1631 [0;32mIn [[1;32m1[0;32m]: [0;00m
1632 1632 \family default
1633 1633
1634 1634 \newline
1635 1635 instead of (in color) something like:
1636 1636 \newline
1637 1637
1638 1638 \family typewriter
1639 1639 In [1]:
1640 1640 \family default
1641 1641
1642 1642 \newline
1643 1643 this means that your terminal doesn't properly handle color escape sequences.
1644 1644 You can go to a 'no color' mode by typing '
1645 1645 \family typewriter
1646 1646 %colors NoColor
1647 1647 \family default
1648 1648 '.
1649 1649
1650 1650 \layout Standard
1651 1651
1652 1652 You can try using a different terminal emulator program.
1653 1653 To permanently set your color preferences, edit the file
1654 1654 \family typewriter
1655 1655 $HOME/.ipython/ipythonrc
1656 1656 \family default
1657 1657 and set the
1658 1658 \family typewriter
1659 1659 colors
1660 1660 \family default
1661 1661 option to the desired value.
1662 1662 \layout Subsubsection
1663 1663
1664 1664 Object details (types, docstrings, source code, etc.)
1665 1665 \layout Standard
1666 1666
1667 1667 IPython has a set of special functions for studying the objects you are
1668 1668 working with, discussed in detail in Sec.
1669 1669
1670 1670 \begin_inset LatexCommand \ref{sec:dyn-object-info}
1671 1671
1672 1672 \end_inset
1673 1673
1674 1674 .
1675 1675 But this system relies on passing information which is longer than your
1676 1676 screen through a data pager, such as the common Unix
1677 1677 \family typewriter
1678 1678 less
1679 1679 \family default
1680 1680 and
1681 1681 \family typewriter
1682 1682 more
1683 1683 \family default
1684 1684 programs.
1685 1685 In order to be able to see this information in color, your pager needs
1686 1686 to be properly configured.
1687 1687 I strongly recommend using
1688 1688 \family typewriter
1689 1689 less
1690 1690 \family default
1691 1691 instead of
1692 1692 \family typewriter
1693 1693 more
1694 1694 \family default
1695 1695 , as it seems that
1696 1696 \family typewriter
1697 1697 more
1698 1698 \family default
1699 1699 simply can not understand colored text correctly.
1700 1700 \layout Standard
1701 1701
1702 1702 In order to configure
1703 1703 \family typewriter
1704 1704 less
1705 1705 \family default
1706 1706 as your default pager, do the following:
1707 1707 \layout Enumerate
1708 1708
1709 1709 Set the environment
1710 1710 \family typewriter
1711 1711 PAGER
1712 1712 \family default
1713 1713 variable to
1714 1714 \family typewriter
1715 1715 less
1716 1716 \family default
1717 1717 .
1718 1718 \layout Enumerate
1719 1719
1720 1720 Set the environment
1721 1721 \family typewriter
1722 1722 LESS
1723 1723 \family default
1724 1724 variable to
1725 1725 \family typewriter
1726 1726 -r
1727 1727 \family default
1728 1728 (plus any other options you always want to pass to
1729 1729 \family typewriter
1730 1730 less
1731 1731 \family default
1732 1732 by default).
1733 1733 This tells
1734 1734 \family typewriter
1735 1735 less
1736 1736 \family default
1737 1737 to properly interpret control sequences, which is how color information
1738 1738 is given to your terminal.
1739 1739 \layout Standard
1740 1740
1741 1741 For the
1742 1742 \family typewriter
1743 1743 csh
1744 1744 \family default
1745 1745 or
1746 1746 \family typewriter
1747 1747 tcsh
1748 1748 \family default
1749 1749 shells, add to your
1750 1750 \family typewriter
1751 1751 ~/.cshrc
1752 1752 \family default
1753 1753 file the lines:
1754 1754 \layout Standard
1755 1755
1756 1756
1757 1757 \family typewriter
1758 1758 setenv PAGER less
1759 1759 \newline
1760 1760 setenv LESS -r
1761 1761 \layout Standard
1762 1762
1763 1763 There is similar syntax for other Unix shells, look at your system documentation
1764 1764 for details.
1765 1765 \layout Standard
1766 1766
1767 1767 If you are on a system which lacks proper data pagers (such as Windows),
1768 1768 IPython will use a very limited builtin pager.
1769 1769 \layout Subsection
1770 1770
1771 1771
1772 1772 \begin_inset LatexCommand \label{sec:emacs}
1773 1773
1774 1774 \end_inset
1775 1775
1776 1776 (X)Emacs configuration
1777 1777 \layout Standard
1778 1778
1779 1779 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently
1780 1780 (X)Emacs and IPython get along very well.
1781 1781
1782 1782 \layout Standard
1783 1783
1784 1784
1785 1785 \series bold
1786 1786 Important note:
1787 1787 \series default
1788 1788 You will need to use a recent enough version of
1789 1789 \family typewriter
1790 1790 python-mode.el
1791 1791 \family default
1792 1792 , along with the file
1793 1793 \family typewriter
1794 1794 ipython.el
1795 1795 \family default
1796 1796 .
1797 1797 You can check that the version you have of
1798 1798 \family typewriter
1799 1799 python-mode.el
1800 1800 \family default
1801 1801 is new enough by either looking at the revision number in the file itself,
1802 1802 or asking for it in (X)Emacs via
1803 1803 \family typewriter
1804 1804 M-x py-version
1805 1805 \family default
1806 1806 .
1807 1807 Versions 4.68 and newer contain the necessary fixes for proper IPython support.
1808 1808 \layout Standard
1809 1809
1810 1810 The file
1811 1811 \family typewriter
1812 1812 ipython.el
1813 1813 \family default
1814 1814 is included with the IPython distribution, in the documentation directory
1815 1815 (where this manual resides in PDF and HTML formats).
1816 1816 \layout Standard
1817 1817
1818 1818 Once you put these files in your Emacs path, all you need in your
1819 1819 \family typewriter
1820 1820 .emacs
1821 1821 \family default
1822 1822 file is:
1823 1823 \layout Standard
1824 1824
1825 1825
1826 1826 \family typewriter
1827 1827 (require 'ipython)
1828 1828 \layout Standard
1829 1829
1830 1830 This should give you full support for executing code snippets via IPython,
1831 1831 opening IPython as your Python shell via
1832 1832 \family typewriter
1833 1833 C-c\SpecialChar ~
1834 1834 !
1835 1835 \family default
1836 1836 , etc.
1837 1837
1838 1838 \layout Subsubsection*
1839 1839
1840 1840 Notes
1841 1841 \layout Itemize
1842 1842
1843 1843 There is one caveat you should be aware of: you must start the IPython shell
1844 1844
1845 1845 \emph on
1846 1846 before
1847 1847 \emph default
1848 1848 attempting to execute any code regions via
1849 1849 \family typewriter
1850 1850 C-c\SpecialChar ~
1851 1851 |
1852 1852 \family default
1853 1853 .
1854 1854 Simply type
1855 1855 \family typewriter
1856 1856 C-c\SpecialChar ~
1857 1857 !
1858 1858 \family default
1859 1859 to start IPython before passing any code regions to the interpreter, and
1860 1860 you shouldn't experience any problems.
1861 1861 \newline
1862 1862 This is due to a bug in Python itself, which has been fixed for Python 2.3,
1863 1863 but exists as of Python 2.2.2 (reported as SF bug [ 737947 ]).
1864 1864 \layout Itemize
1865 1865
1866 1866 The (X)Emacs support is maintained by Alexander Schmolck, so all comments/reques
1867 1867 ts should be directed to him through the IPython mailing lists.
1868 1868
1869 1869 \layout Itemize
1870 1870
1871 1871 This code is still somewhat experimental so it's a bit rough around the
1872 1872 edges (although in practice, it works quite well).
1873 1873 \layout Itemize
1874 1874
1875 1875 Be aware that if you customize
1876 1876 \family typewriter
1877 1877 py-python-command
1878 1878 \family default
1879 1879 previously, this value will override what
1880 1880 \family typewriter
1881 1881 ipython.el
1882 1882 \family default
1883 1883 does (because loading the customization variables comes later).
1884 1884 \layout Section
1885 1885
1886 1886
1887 1887 \begin_inset LatexCommand \label{sec:quick_tips}
1888 1888
1889 1889 \end_inset
1890 1890
1891 1891 Quick tips
1892 1892 \layout Standard
1893 1893
1894 1894 IPython can be used as an improved replacement for the Python prompt, and
1895 1895 for that you don't really need to read any more of this manual.
1896 1896 But in this section we'll try to summarize a few tips on how to make the
1897 1897 most effective use of it for everyday Python development, highlighting
1898 1898 things you might miss in the rest of the manual (which is getting long).
1899 1899 We'll give references to parts in the manual which provide more detail
1900 1900 when appropriate.
1901 1901 \layout Standard
1902 1902
1903 1903 The following article by Jeremy Jones provides an introductory tutorial
1904 1904 about IPython:
1905 1905 \newline
1906 1906
1907 1907 \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html}
1908 1908
1909 1909 \end_inset
1910 1910
1911 1911
1912 1912 \layout Itemize
1913 1913
1914 1914 The TAB key.
1915 1915 TAB-completion, especially for attributes, is a convenient way to explore
1916 1916 the structure of any object you're dealing with.
1917 1917 Simply type
1918 1918 \family typewriter
1919 1919 object_name.<TAB>
1920 1920 \family default
1921 1921 and a list of the object's attributes will be printed (see sec.
1922 1922
1923 1923 \begin_inset LatexCommand \ref{sec:readline}
1924 1924
1925 1925 \end_inset
1926 1926
1927 1927 for more).
1928 1928 Tab completion also works on file and directory names, which combined with
1929 1929 IPython's alias system allows you to do from within IPython many of the
1930 1930 things you normally would need the system shell for.
1931 1931
1932 1932 \layout Itemize
1933 1933
1934 1934 Explore your objects.
1935 1935 Typing
1936 1936 \family typewriter
1937 1937 object_name?
1938 1938 \family default
1939 1939 will print all sorts of details about any object, including docstrings,
1940 1940 function definition lines (for call arguments) and constructor details
1941 1941 for classes.
1942 1942 The magic commands
1943 1943 \family typewriter
1944 1944 %pdoc
1945 1945 \family default
1946 1946 ,
1947 1947 \family typewriter
1948 1948 %pdef
1949 1949 \family default
1950 1950 ,
1951 1951 \family typewriter
1952 1952 %psource
1953 1953 \family default
1954 1954 and
1955 1955 \family typewriter
1956 1956 %pfile
1957 1957 \family default
1958 1958 will respectively print the docstring, function definition line, full source
1959 1959 code and the complete file for any object (when they can be found).
1960 1960 If automagic is on (it is by default), you don't need to type the '
1961 1961 \family typewriter
1962 1962 %
1963 1963 \family default
1964 1964 ' explicitly.
1965 1965 See sec.
1966 1966
1967 1967 \begin_inset LatexCommand \ref{sec:dyn-object-info}
1968 1968
1969 1969 \end_inset
1970 1970
1971 1971 for more.
1972 1972 \layout Itemize
1973 1973
1974 1974 The
1975 1975 \family typewriter
1976 1976 %run
1977 1977 \family default
1978 1978 magic command allows you to run any python script and load all of its data
1979 1979 directly into the interactive namespace.
1980 1980 Since the file is re-read from disk each time, changes you make to it are
1981 1981 reflected immediately (in contrast to the behavior of
1982 1982 \family typewriter
1983 1983 import
1984 1984 \family default
1985 1985 ).
1986 1986 I rarely use
1987 1987 \family typewriter
1988 1988 import
1989 1989 \family default
1990 1990 for code I am testing, relying on
1991 1991 \family typewriter
1992 1992 %run
1993 1993 \family default
1994 1994 instead.
1995 1995 See sec.
1996 1996
1997 1997 \begin_inset LatexCommand \ref{sec:magic}
1998 1998
1999 1999 \end_inset
2000 2000
2001 2001 for more on this and other magic commands, or type the name of any magic
2002 2002 command and ? to get details on it.
2003 2003 See also sec.
2004 2004
2005 2005 \begin_inset LatexCommand \ref{sec:dreload}
2006 2006
2007 2007 \end_inset
2008 2008
2009 2009 for a recursive reload command.
2010 2010 \newline
2011 2011
2012 2012 \family typewriter
2013 2013 %run
2014 2014 \family default
2015 2015 also has special flags for timing the execution of your scripts (
2016 2016 \family typewriter
2017 2017 -t
2018 2018 \family default
2019 2019 ) and for executing them under the control of either Python's
2020 2020 \family typewriter
2021 2021 pdb
2022 2022 \family default
2023 2023 debugger (
2024 2024 \family typewriter
2025 2025 -d
2026 2026 \family default
2027 2027 ) or profiler (
2028 2028 \family typewriter
2029 2029 -p
2030 2030 \family default
2031 2031 ).
2032 2032 With all of these,
2033 2033 \family typewriter
2034 2034 %run
2035 2035 \family default
2036 2036 can be used as the main tool for efficient interactive development of code
2037 2037 which you write in your editor of choice.
2038 2038 \layout Itemize
2039 2039
2040 2040 Use the Python debugger,
2041 2041 \family typewriter
2042 2042 pdb
2043 2043 \family default
2044 2044
2045 2045 \begin_inset Foot
2046 2046 collapsed true
2047 2047
2048 2048 \layout Standard
2049 2049
2050 2050 Thanks to Christian Hart and Matthew Arnison for the suggestions leading
2051 2051 to IPython's improved debugger and profiler support.
2052 2052 \end_inset
2053 2053
2054 2054 .
2055 2055 The
2056 2056 \family typewriter
2057 2057 %pdb
2058 2058 \family default
2059 2059 command allows you to toggle on and off the automatic invocation of an
2060 2060 IPython-enhanced
2061 2061 \family typewriter
2062 2062 pdb
2063 2063 \family default
2064 2064 debugger (with coloring, tab completion and more) at any uncaught exception.
2065 2065 The advantage of this is that
2066 2066 \family typewriter
2067 2067 pdb
2068 2068 \family default
2069 2069 starts
2070 2070 \emph on
2071 2071 inside
2072 2072 \emph default
2073 2073 the function where the exception occurred, with all data still available.
2074 2074 You can print variables, see code, execute statements and even walk up
2075 2075 and down the call stack to track down the true source of the problem (which
2076 2076 often is many layers in the stack above where the exception gets triggered).
2077 2077 \newline
2078 2078 Running programs with
2079 2079 \family typewriter
2080 2080 %run
2081 2081 \family default
2082 2082 and pdb active can be an efficient to develop and debug code, in many cases
2083 2083 eliminating the need for
2084 2084 \family typewriter
2085 2085 print
2086 2086 \family default
2087 2087 statements or external debugging tools.
2088 2088 I often simply put a
2089 2089 \family typewriter
2090 2090 1/0
2091 2091 \family default
2092 2092 in a place where I want to take a look so that pdb gets called, quickly
2093 2093 view whatever variables I need to or test various pieces of code and then
2094 2094 remove the
2095 2095 \family typewriter
2096 2096 1/0
2097 2097 \family default
2098 2098 .
2099 2099 \newline
2100 2100 Note also that `
2101 2101 \family typewriter
2102 2102 %run -d
2103 2103 \family default
2104 2104 ' activates
2105 2105 \family typewriter
2106 2106 pdb
2107 2107 \family default
2108 2108 and automatically sets initial breakpoints for you to step through your
2109 2109 code, watch variables, etc.
2110 2110 See Sec.\SpecialChar ~
2111 2111
2112 2112 \begin_inset LatexCommand \ref{sec:cache_output}
2113 2113
2114 2114 \end_inset
2115 2115
2116 2116 for details.
2117 2117 \layout Itemize
2118 2118
2119 2119 Use the output cache.
2120 2120 All output results are automatically stored in a global dictionary named
2121 2121
2122 2122 \family typewriter
2123 2123 Out
2124 2124 \family default
2125 2125 and variables named
2126 2126 \family typewriter
2127 2127 _1
2128 2128 \family default
2129 2129 ,
2130 2130 \family typewriter
2131 2131 _2
2132 2132 \family default
2133 2133 , etc.
2134 2134 alias them.
2135 2135 For example, the result of input line 4 is available either as
2136 2136 \family typewriter
2137 2137 Out[4]
2138 2138 \family default
2139 2139 or as
2140 2140 \family typewriter
2141 2141 _4
2142 2142 \family default
2143 2143 .
2144 2144 Additionally, three variables named
2145 2145 \family typewriter
2146 2146 _
2147 2147 \family default
2148 2148 ,
2149 2149 \family typewriter
2150 2150 __
2151 2151 \family default
2152 2152 and
2153 2153 \family typewriter
2154 2154 ___
2155 2155 \family default
2156 2156 are always kept updated with the for the last three results.
2157 2157 This allows you to recall any previous result and further use it for new
2158 2158 calculations.
2159 2159 See Sec.\SpecialChar ~
2160 2160
2161 2161 \begin_inset LatexCommand \ref{sec:cache_output}
2162 2162
2163 2163 \end_inset
2164 2164
2165 2165 for more.
2166 2166 \layout Itemize
2167 2167
2168 2168 Put a '
2169 2169 \family typewriter
2170 2170 ;
2171 2171 \family default
2172 2172 ' at the end of a line to supress the printing of output.
2173 2173 This is useful when doing calculations which generate long output you are
2174 2174 not interested in seeing.
2175 2175 The
2176 2176 \family typewriter
2177 2177 _*
2178 2178 \family default
2179 2179 variables and the
2180 2180 \family typewriter
2181 2181 Out[]
2182 2182 \family default
2183 2183 list do get updated with the contents of the output, even if it is not
2184 2184 printed.
2185 2185 You can thus still access the generated results this way for further processing.
2186 2186 \layout Itemize
2187 2187
2188 2188 A similar system exists for caching input.
2189 2189 All input is stored in a global list called
2190 2190 \family typewriter
2191 2191 In
2192 2192 \family default
2193 2193 , so you can re-execute lines 22 through 28 plus line 34 by typing
2194 2194 \family typewriter
2195 2195 'exec In[22:29]+In[34]'
2196 2196 \family default
2197 2197 (using Python slicing notation).
2198 2198 If you need to execute the same set of lines often, you can assign them
2199 2199 to a macro with the
2200 2200 \family typewriter
2201 2201 %macro
2202 2202 \family default
2203 2203
2204 2204 \family typewriter
2205 2205 function.
2206 2206
2207 2207 \family default
2208 2208 See sec.
2209 2209
2210 2210 \begin_inset LatexCommand \ref{sec:cache_input}
2211 2211
2212 2212 \end_inset
2213 2213
2214 2214 for more.
2215 2215 \layout Itemize
2216 2216
2217 2217 Use your input history.
2218 2218 The
2219 2219 \family typewriter
2220 2220 %hist
2221 2221 \family default
2222 2222 command can show you all previous input, without line numbers if desired
2223 2223 (option
2224 2224 \family typewriter
2225 2225 -n
2226 2226 \family default
2227 2227 ) so you can directly copy and paste code either back in IPython or in a
2228 2228 text editor.
2229 2229 You can also save all your history by turning on logging via
2230 2230 \family typewriter
2231 2231 %logstart
2232 2232 \family default
2233 2233 ; these logs can later be either reloaded as IPython sessions or used as
2234 2234 code for your programs.
2235 2235 \layout Itemize
2236 2236
2237 2237 Define your own system aliases.
2238 2238 Even though IPython gives you access to your system shell via the
2239 2239 \family typewriter
2240 2240 !
2241 2241 \family default
2242 2242 prefix, it is convenient to have aliases to the system commands you use
2243 2243 most often.
2244 2244 This allows you to work seamlessly from inside IPython with the same commands
2245 2245 you are used to in your system shell.
2246 2246 \newline
2247 2247 IPython comes with some pre-defined aliases and a complete system for changing
2248 2248 directories, both via a stack (see
2249 2249 \family typewriter
2250 2250 %pushd
2251 2251 \family default
2252 2252 ,
2253 2253 \family typewriter
2254 2254 %popd
2255 2255 \family default
2256 2256 and
2257 2257 \family typewriter
2258 2258 %ds
2259 2259 \family default
2260 2260 ) and via direct
2261 2261 \family typewriter
2262 2262 %cd
2263 2263 \family default
2264 2264 .
2265 2265 The latter keeps a history of visited directories and allows you to go
2266 2266 to any previously visited one.
2267 2267 \layout Itemize
2268 2268
2269 2269 Use Python to manipulate the results of system commands.
2270 2270 The `
2271 2271 \family typewriter
2272 2272 !!
2273 2273 \family default
2274 2274 ' special syntax, and the
2275 2275 \family typewriter
2276 2276 %sc
2277 2277 \family default
2278 2278 and
2279 2279 \family typewriter
2280 2280 %sx
2281 2281 \family default
2282 2282 magic commands allow you to capture system output into Python variables.
2283 2283 \layout Itemize
2284 2284
2285 2285 Expand python variables when calling the shell (either via
2286 2286 \family typewriter
2287 2287 `!'
2288 2288 \family default
2289 2289 and
2290 2290 \family typewriter
2291 2291 `!!'
2292 2292 \family default
2293 2293 or via aliases) by prepending a
2294 2294 \family typewriter
2295 2295 $
2296 2296 \family default
2297 2297 in front of them.
2298 2298 You can also expand complete python expressions.
2299 2299 See sec.\SpecialChar ~
2300 2300
2301 2301 \begin_inset LatexCommand \ref{sub:System-shell-access}
2302 2302
2303 2303 \end_inset
2304 2304
2305 2305 for more.
2306 2306 \layout Itemize
2307 2307
2308 2308 Use profiles to maintain different configurations (modules to load, function
2309 2309 definitions, option settings) for particular tasks.
2310 2310 You can then have customized versions of IPython for specific purposes.
2311 2311 See sec.\SpecialChar ~
2312 2312
2313 2313 \begin_inset LatexCommand \ref{sec:profiles}
2314 2314
2315 2315 \end_inset
2316 2316
2317 2317 for more.
2318 2318 \layout Itemize
2319 2319
2320 2320 Embed IPython in your programs.
2321 2321 A few lines of code are enough to load a complete IPython inside your own
2322 2322 programs, giving you the ability to work with your data interactively after
2323 2323 automatic processing has been completed.
2324 2324 See sec.\SpecialChar ~
2325 2325
2326 2326 \begin_inset LatexCommand \ref{sec:embed}
2327 2327
2328 2328 \end_inset
2329 2329
2330 2330 for more.
2331 2331 \layout Itemize
2332 2332
2333 2333 Use the Python profiler.
2334 2334 When dealing with performance issues, the
2335 2335 \family typewriter
2336 2336 %run
2337 2337 \family default
2338 2338 command with a
2339 2339 \family typewriter
2340 2340 -p
2341 2341 \family default
2342 2342 option allows you to run complete programs under the control of the Python
2343 2343 profiler.
2344 2344 The
2345 2345 \family typewriter
2346 2346 %prun
2347 2347 \family default
2348 2348 command does a similar job for single Python expressions (like function
2349 2349 calls).
2350 2350 \layout Itemize
2351 2351
2352 2352 Use the IPython.demo.Demo class to load any Python script as an interactive
2353 2353 demo.
2354 2354 With a minimal amount of simple markup, you can control the execution of
2355 2355 the script, stopping as needed.
2356 2356 See sec.\SpecialChar ~
2357 2357
2358 2358 \begin_inset LatexCommand \ref{sec:interactive-demos}
2359 2359
2360 2360 \end_inset
2361 2361
2362 2362 for more.
2363 2363 \layout Subsection
2364 2364
2365 2365 Source code handling tips
2366 2366 \layout Standard
2367 2367
2368 2368 IPython is a line-oriented program, without full control of the terminal.
2369 2369 Therefore, it doesn't support true multiline editing.
2370 2370 However, it has a number of useful tools to help you in dealing effectively
2371 2371 with more complex editing.
2372 2372 \layout Standard
2373 2373
2374 2374 The
2375 2375 \family typewriter
2376 2376 %edit
2377 2377 \family default
2378 2378 command gives a reasonable approximation of multiline editing, by invoking
2379 2379 your favorite editor on the spot.
2380 2380 IPython will execute the code you type in there as if it were typed interactive
2381 2381 ly.
2382 2382 Type
2383 2383 \family typewriter
2384 2384 %edit?
2385 2385 \family default
2386 2386 for the full details on the edit command.
2387 2387 \layout Standard
2388 2388
2389 2389 If you have typed various commands during a session, which you'd like to
2390 2390 reuse, IPython provides you with a number of tools.
2391 2391 Start by using
2392 2392 \family typewriter
2393 2393 %hist
2394 2394 \family default
2395 2395 to see your input history, so you can see the line numbers of all input.
2396 2396 Let us say that you'd like to reuse lines 10 through 20, plus lines 24
2397 2397 and 28.
2398 2398 All the commands below can operate on these with the syntax
2399 2399 \layout LyX-Code
2400 2400
2401 2401 %command 10-20 24 28
2402 2402 \layout Standard
2403 2403
2404 2404 where the command given can be:
2405 2405 \layout Itemize
2406 2406
2407 2407
2408 2408 \family typewriter
2409 2409 %macro <macroname>
2410 2410 \family default
2411 2411 : this stores the lines into a variable which, when called at the prompt,
2412 2412 re-executes the input.
2413 2413 Macros can be edited later using
2414 2414 \family typewriter
2415 2415 `%edit macroname
2416 2416 \family default
2417 2417 ', and they can be stored persistently across sessions with `
2418 2418 \family typewriter
2419 2419 %store macroname
2420 2420 \family default
2421 2421 ' (the storage system is per-profile).
2422 2422 The combination of quick macros, persistent storage and editing, allows
2423 2423 you to easily refine quick-and-dirty interactive input into permanent utilities
2424 2424 , always available both in IPython and as files for general reuse.
2425 2425 \layout Itemize
2426 2426
2427 2427
2428 2428 \family typewriter
2429 2429 %edit
2430 2430 \family default
2431 2431 : this will open a text editor with those lines pre-loaded for further modificat
2432 2432 ion.
2433 2433 It will then execute the resulting file's contents as if you had typed
2434 2434 it at the prompt.
2435 2435 \layout Itemize
2436 2436
2437 2437
2438 2438 \family typewriter
2439 2439 %save <filename>
2440 2440 \family default
2441 2441 : this saves the lines directly to a named file on disk.
2442 2442 \layout Standard
2443 2443
2444 2444 While
2445 2445 \family typewriter
2446 2446 %macro
2447 2447 \family default
2448 2448 saves input lines into memory for interactive re-execution, sometimes you'd
2449 2449 like to save your input directly to a file.
2450 2450 The
2451 2451 \family typewriter
2452 2452 %save
2453 2453 \family default
2454 2454 magic does this: its input sytnax is the same as
2455 2455 \family typewriter
2456 2456 %macro
2457 2457 \family default
2458 2458 , but it saves your input directly to a Python file.
2459 2459 Note that the
2460 2460 \family typewriter
2461 2461 %logstart
2462 2462 \family default
2463 2463 command also saves input, but it logs
2464 2464 \emph on
2465 2465 all
2466 2466 \emph default
2467 2467 input to disk (though you can temporarily suspend it and reactivate it
2468 2468 with
2469 2469 \family typewriter
2470 2470 %logoff/%logon
2471 2471 \family default
2472 2472 );
2473 2473 \family typewriter
2474 2474 %save
2475 2475 \family default
2476 2476 allows you to select which lines of input you need to save.
2477 2477 \layout Subsection
2478 2478
2479 2479 Effective logging
2480 2480 \layout Standard
2481 2481
2482 2482 A very useful suggestion sent in by Robert Kern follows:
2483 2483 \layout Standard
2484 2484
2485 2485 I recently happened on a nifty way to keep tidy per-project log files.
2486 2486 I made a profile for my project (which is called "parkfield").
2487 2487 \layout LyX-Code
2488 2488
2489 2489 include ipythonrc
2490 2490 \layout LyX-Code
2491 2491
2492 2492 logfile '' # cancel earlier logfile invocation
2493 2493 \layout LyX-Code
2494 2494
2495 2495 execute import time
2496 2496 \layout LyX-Code
2497 2497
2498 2498 execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
2499 2499 \layout LyX-Code
2500 2500
2501 2501 execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
2502 2502 \layout Standard
2503 2503
2504 2504 I also added a shell alias for convenience:
2505 2505 \layout LyX-Code
2506 2506
2507 2507 alias parkfield="ipython -pylab -profile parkfield"
2508 2508 \layout Standard
2509 2509
2510 2510 Now I have a nice little directory with everything I ever type in, organized
2511 2511 by project and date.
2512 2512 \layout Standard
2513 2513
2514 2514
2515 2515 \series bold
2516 2516 Contribute your own:
2517 2517 \series default
2518 2518 If you have your own favorite tip on using IPython efficiently for a certain
2519 2519 task (especially things which can't be done in the normal Python interpreter),
2520 2520 don't hesitate to send it!
2521 2521 \layout Section
2522 2522
2523 2523 Command-line use
2524 2524 \layout Standard
2525 2525
2526 2526 You start IPython with the command:
2527 2527 \layout Standard
2528 2528
2529 2529
2530 2530 \family typewriter
2531 2531 $ ipython [options] files
2532 2532 \layout Standard
2533 2533
2534 2534 If invoked with no options, it executes all the files listed in sequence
2535 2535 and drops you into the interpreter while still acknowledging any options
2536 2536 you may have set in your ipythonrc file.
2537 2537 This behavior is different from standard Python, which when called as
2538 2538 \family typewriter
2539 2539 python -i
2540 2540 \family default
2541 2541 will only execute one file and ignore your configuration setup.
2542 2542 \layout Standard
2543 2543
2544 2544 Please note that some of the configuration options are not available at
2545 2545 the command line, simply because they are not practical here.
2546 2546 Look into your ipythonrc configuration file for details on those.
2547 2547 This file typically installed in the
2548 2548 \family typewriter
2549 2549 $HOME/.ipython
2550 2550 \family default
2551 2551 directory.
2552 2552 For Windows users,
2553 2553 \family typewriter
2554 2554 $HOME
2555 2555 \family default
2556 2556 resolves to
2557 2557 \family typewriter
2558 2558 C:
2559 2559 \backslash
2560 2560
2561 2561 \backslash
2562 2562 Documents and Settings
2563 2563 \backslash
2564 2564
2565 2565 \backslash
2566 2566 YourUserName
2567 2567 \family default
2568 2568 in most instances.
2569 2569 In the rest of this text, we will refer to this directory as
2570 2570 \family typewriter
2571 2571 IPYTHONDIR
2572 2572 \family default
2573 2573 .
2574 2574 \layout Subsection
2575 2575
2576 2576
2577 2577 \begin_inset LatexCommand \label{sec:threading-opts}
2578 2578
2579 2579 \end_inset
2580 2580
2581 2581 Special Threading Options
2582 2582 \layout Standard
2583 2583
2584 2584 The following special options are ONLY valid at the beginning of the command
2585 2585 line, and not later.
2586 2586 This is because they control the initial- ization of ipython itself, before
2587 2587 the normal option-handling mechanism is active.
2588 2588 \layout List
2589 2589 \labelwidthstring 00.00.0000
2590 2590
2591 2591
2592 2592 \family typewriter
2593 2593 \series bold
2594 2594 -gthread,\SpecialChar ~
2595 2595 -qthread,\SpecialChar ~
2596 2596 -wthread,\SpecialChar ~
2597 2597 -pylab:
2598 2598 \family default
2599 2599 \series default
2600 2600 Only
2601 2601 \emph on
2602 2602 one
2603 2603 \emph default
2604 2604 of these can be given, and it can only be given as the first option passed
2605 2605 to IPython (it will have no effect in any other position).
2606 2606 They provide threading support for the GTK Qt and WXPython toolkits, and
2607 2607 for the matplotlib library.
2608 2608 \layout List
2609 2609 \labelwidthstring 00.00.0000
2610 2610
2611 2611 \SpecialChar ~
2612 2612 With any of the first three options, IPython starts running a separate
2613 2613 thread for the graphical toolkit's operation, so that you can open and
2614 2614 control graphical elements from within an IPython command line, without
2615 2615 blocking.
2616 2616 All three provide essentially the same functionality, respectively for
2617 2617 GTK, QT and WXWidgets (via their Python interfaces).
2618 2618 \layout List
2619 2619 \labelwidthstring 00.00.0000
2620 2620
2621 2621 \SpecialChar ~
2622 2622 Note that with
2623 2623 \family typewriter
2624 2624 -wthread
2625 2625 \family default
2626 2626 , you can additionally use the -wxversion option to request a specific version
2627 2627 of wx to be used.
2628 2628 This requires that you have the
2629 2629 \family typewriter
2630 2630 wxversion
2631 2631 \family default
2632 2632 Python module installed, which is part of recent wxPython distributions.
2633 2633 \layout List
2634 2634 \labelwidthstring 00.00.0000
2635 2635
2636 2636 \SpecialChar ~
2637 2637 If
2638 2638 \family typewriter
2639 2639 -pylab
2640 2640 \family default
2641 2641 is given, IPython loads special support for the mat plotlib library (
2642 2642 \begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}
2643 2643
2644 2644 \end_inset
2645 2645
2646 2646 ), allowing interactive usage of any of its backends as defined in the user's
2647 2647
2648 2648 \family typewriter
2649 2649 ~/.matplotlib/matplotlibrc
2650 2650 \family default
2651 2651 file.
2652 2652 It automatically activates GTK, Qt or WX threading for IPyhton if the choice
2653 2653 of matplotlib backend requires it.
2654 2654 It also modifies the
2655 2655 \family typewriter
2656 2656 %run
2657 2657 \family default
2658 2658 command to correctly execute (without blocking) any matplotlib-based script
2659 2659 which calls
2660 2660 \family typewriter
2661 2661 show()
2662 2662 \family default
2663 2663 at the end.
2664 2664
2665 2665 \layout List
2666 2666 \labelwidthstring 00.00.0000
2667 2667
2668 2668
2669 2669 \family typewriter
2670 2670 \series bold
2671 2671 -tk
2672 2672 \family default
2673 2673 \series default
2674 2674 The
2675 2675 \family typewriter
2676 2676 -g/q/wthread
2677 2677 \family default
2678 2678 options, and
2679 2679 \family typewriter
2680 2680 -pylab
2681 2681 \family default
2682 2682 (if matplotlib is configured to use GTK, Qt or WX), will normally block
2683 2683 Tk graphical interfaces.
2684 2684 This means that when either GTK, Qt or WX threading is active, any attempt
2685 2685 to open a Tk GUI will result in a dead window, and possibly cause the Python
2686 2686 interpreter to crash.
2687 2687 An extra option,
2688 2688 \family typewriter
2689 2689 -tk
2690 2690 \family default
2691 2691 , is available to address this issue.
2692 2692 It can
2693 2693 \emph on
2694 2694 only
2695 2695 \emph default
2696 2696 be given as a
2697 2697 \emph on
2698 2698 second
2699 2699 \emph default
2700 2700 option after any of the above (
2701 2701 \family typewriter
2702 2702 -gthread
2703 2703 \family default
2704 2704 ,
2705 2705 \family typewriter
2706 2706 -wthread
2707 2707 \family default
2708 2708 or
2709 2709 \family typewriter
2710 2710 -pylab
2711 2711 \family default
2712 2712 ).
2713 2713 \layout List
2714 2714 \labelwidthstring 00.00.0000
2715 2715
2716 2716 \SpecialChar ~
2717 2717 If
2718 2718 \family typewriter
2719 2719 -tk
2720 2720 \family default
2721 2721 is given, IPython will try to coordinate Tk threading with GTK, Qt or WX.
2722 2722 This is however potentially unreliable, and you will have to test on your
2723 2723 platform and Python configuration to determine whether it works for you.
2724 2724 Debian users have reported success, apparently due to the fact that Debian
2725 2725 builds all of Tcl, Tk, Tkinter and Python with pthreads support.
2726 2726 Under other Linux environments (such as Fedora Core 2/3), this option has
2727 2727 caused random crashes and lockups of the Python interpreter.
2728 2728 Under other operating systems (Mac OSX and Windows), you'll need to try
2729 2729 it to find out, since currently no user reports are available.
2730 2730 \layout List
2731 2731 \labelwidthstring 00.00.0000
2732 2732
2733 2733 \SpecialChar ~
2734 2734 There is unfortunately no way for IPython to determine at run time whether
2735 2735
2736 2736 \family typewriter
2737 2737 -tk
2738 2738 \family default
2739 2739 will work reliably or not, so you will need to do some experiments before
2740 2740 relying on it for regular work.
2741 2741
2742 2742 \layout Subsection
2743 2743
2744 2744
2745 2745 \begin_inset LatexCommand \label{sec:cmd-line-opts}
2746 2746
2747 2747 \end_inset
2748 2748
2749 2749 Regular Options
2750 2750 \layout Standard
2751 2751
2752 2752 After the above threading options have been given, regular options can follow
2753 2753 in any order.
2754 2754 All options can be abbreviated to their shortest non-ambiguous form and
2755 2755 are case-sensitive.
2756 2756 One or two dashes can be used.
2757 2757 Some options have an alternate short form, indicated after a
2758 2758 \family typewriter
2759 2759 |
2760 2760 \family default
2761 2761 .
2762 2762 \layout Standard
2763 2763
2764 2764 Most options can also be set from your ipythonrc configuration file.
2765 2765 See the provided example for more details on what the options do.
2766 2766 Options given at the command line override the values set in the ipythonrc
2767 2767 file.
2768 2768 \layout Standard
2769 2769
2770 2770 All options with a
2771 2771 \family typewriter
2772 2772 [no]
2773 2773 \family default
2774 2774 prepended can be specified in negated form (
2775 2775 \family typewriter
2776 2776 -nooption
2777 2777 \family default
2778 2778 instead of
2779 2779 \family typewriter
2780 2780 -option
2781 2781 \family default
2782 2782 ) to turn the feature off.
2783 2783 \layout List
2784 2784 \labelwidthstring 00.00.0000
2785 2785
2786 2786
2787 2787 \family typewriter
2788 2788 \series bold
2789 2789 -help
2790 2790 \family default
2791 2791 \series default
2792 2792 : print a help message and exit.
2793 2793 \layout List
2794 2794 \labelwidthstring 00.00.0000
2795 2795
2796 2796
2797 2797 \family typewriter
2798 2798 \series bold
2799 2799 -pylab:
2800 2800 \family default
2801 2801 \series default
2802 2802 this can
2803 2803 \emph on
2804 2804 only
2805 2805 \emph default
2806 2806 be given as the
2807 2807 \emph on
2808 2808 first
2809 2809 \emph default
2810 2810 option passed to IPython (it will have no effect in any other position).
2811 2811 It adds special support for the matplotlib library (
2812 2812 \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
2813 2813
2814 2814 \end_inset
2815 2815
2816 2816 ), allowing interactive usage of any of its backends as defined in the user's
2817 2817
2818 2818 \family typewriter
2819 2819 .matplotlibrc
2820 2820 \family default
2821 2821 file.
2822 2822 It automatically activates GTK or WX threading for IPyhton if the choice
2823 2823 of matplotlib backend requires it.
2824 2824 It also modifies the
2825 2825 \family typewriter
2826 2826 %run
2827 2827 \family default
2828 2828 command to correctly execute (without blocking) any matplotlib-based script
2829 2829 which calls
2830 2830 \family typewriter
2831 2831 show()
2832 2832 \family default
2833 2833 at the end.
2834 2834 See Sec.\SpecialChar ~
2835 2835
2836 2836 \begin_inset LatexCommand \ref{sec:matplotlib-support}
2837 2837
2838 2838 \end_inset
2839 2839
2840 2840 for more details.
2841 2841 \layout List
2842 2842 \labelwidthstring 00.00.0000
2843 2843
2844 2844
2845 2845 \family typewriter
2846 2846 \series bold
2847 2847 -autocall <val>:
2848 2848 \family default
2849 2849 \series default
2850 2850 Make IPython automatically call any callable object even if you didn't
2851 2851 type explicit parentheses.
2852 2852 For example, `str 43' becomes `str(43)' automatically.
2853 2853 The value can be `0' to disable the feature, `1' for
2854 2854 \emph on
2855 2855 smart
2856 2856 \emph default
2857 2857 autocall, where it is not applied if there are no more arguments on the
2858 2858 line, and `2' for
2859 2859 \emph on
2860 2860 full
2861 2861 \emph default
2862 2862 autocall, where all callable objects are automatically called (even if
2863 2863 no arguments are present).
2864 2864 The default is `1'.
2865 2865 \layout List
2866 2866 \labelwidthstring 00.00.0000
2867 2867
2868 2868
2869 2869 \family typewriter
2870 2870 \series bold
2871 2871 -[no]autoindent:
2872 2872 \family default
2873 2873 \series default
2874 2874 Turn automatic indentation on/off.
2875 2875 \layout List
2876 2876 \labelwidthstring 00.00.0000
2877 2877
2878 2878
2879 2879 \family typewriter
2880 2880 \series bold
2881 2881 -[no]automagic
2882 2882 \series default
2883 2883 :
2884 2884 \family default
2885 2885 make magic commands automatic (without needing their first character to
2886 2886 be
2887 2887 \family typewriter
2888 2888 %
2889 2889 \family default
2890 2890 ).
2891 2891 Type
2892 2892 \family typewriter
2893 2893 %magic
2894 2894 \family default
2895 2895 at the IPython prompt for more information.
2896 2896 \layout List
2897 2897 \labelwidthstring 00.00.0000
2898 2898
2899 2899
2900 2900 \family typewriter
2901 2901 \series bold
2902 2902 -[no]autoedit_syntax:
2903 2903 \family default
2904 2904 \series default
2905 2905 When a syntax error occurs after editing a file, automatically open the
2906 2906 file to the trouble causing line for convenient fixing.
2907 2907
2908 2908 \layout List
2909 2909 \labelwidthstring 00.00.0000
2910 2910
2911 2911
2912 2912 \family typewriter
2913 2913 \series bold
2914 2914 -[no]banner
2915 2915 \series default
2916 2916 :
2917 2917 \family default
2918 2918 Print the initial information banner (default on).
2919 2919 \layout List
2920 2920 \labelwidthstring 00.00.0000
2921 2921
2922 2922
2923 2923 \family typewriter
2924 2924 \series bold
2925 2925 -c\SpecialChar ~
2926 2926 <command>:
2927 2927 \family default
2928 2928 \series default
2929 2929 execute the given command string, and set sys.argv to
2930 2930 \family typewriter
2931 2931 ['c']
2932 2932 \family default
2933 2933 .
2934 2934 This is similar to the
2935 2935 \family typewriter
2936 2936 -c
2937 2937 \family default
2938 2938 option in the normal Python interpreter.
2939 2939
2940 2940 \layout List
2941 2941 \labelwidthstring 00.00.0000
2942 2942
2943 2943
2944 2944 \family typewriter
2945 2945 \series bold
2946 2946 -cache_size|cs\SpecialChar ~
2947 2947 <n>
2948 2948 \series default
2949 2949 :
2950 2950 \family default
2951 2951 size of the output cache (maximum number of entries to hold in memory).
2952 2952 The default is 1000, you can change it permanently in your config file.
2953 2953 Setting it to 0 completely disables the caching system, and the minimum
2954 2954 value accepted is 20 (if you provide a value less than 20, it is reset
2955 2955 to 0 and a warning is issued) This limit is defined because otherwise you'll
2956 2956 spend more time re-flushing a too small cache than working.
2957 2957 \layout List
2958 2958 \labelwidthstring 00.00.0000
2959 2959
2960 2960
2961 2961 \family typewriter
2962 2962 \series bold
2963 2963 -classic|cl
2964 2964 \series default
2965 2965 :
2966 2966 \family default
2967 2967 Gives IPython a similar feel to the classic Python prompt.
2968 2968 \layout List
2969 2969 \labelwidthstring 00.00.0000
2970 2970
2971 2971
2972 2972 \family typewriter
2973 2973 \series bold
2974 2974 -colors\SpecialChar ~
2975 2975 <scheme>:
2976 2976 \family default
2977 2977 \series default
2978 2978 Color scheme for prompts and exception reporting.
2979 2979 Currently implemented: NoColor, Linux and LightBG.
2980 2980 \layout List
2981 2981 \labelwidthstring 00.00.0000
2982 2982
2983 2983
2984 2984 \family typewriter
2985 2985 \series bold
2986 2986 -[no]color_info:
2987 2987 \family default
2988 2988 \series default
2989 2989 IPython can display information about objects via a set of functions, and
2990 2990 optionally can use colors for this, syntax highlighting source code and
2991 2991 various other elements.
2992 2992 However, because this information is passed through a pager (like 'less')
2993 2993 and many pagers get confused with color codes, this option is off by default.
2994 2994 You can test it and turn it on permanently in your ipythonrc file if it
2995 2995 works for you.
2996 2996 As a reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
2997 2997 that in RedHat 7.2 doesn't.
2998 2998 \layout List
2999 2999 \labelwidthstring 00.00.0000
3000 3000
3001 3001 \SpecialChar ~
3002 3002 Test it and turn it on permanently if it works with your system.
3003 3003 The magic function
3004 3004 \family typewriter
3005 3005 %color_info
3006 3006 \family default
3007 3007 allows you to toggle this interactively for testing.
3008 3008 \layout List
3009 3009 \labelwidthstring 00.00.0000
3010 3010
3011 3011
3012 3012 \family typewriter
3013 3013 \series bold
3014 3014 -[no]debug
3015 3015 \family default
3016 3016 \series default
3017 3017 : Show information about the loading process.
3018 3018 Very useful to pin down problems with your configuration files or to get
3019 3019 details about session restores.
3020 3020 \layout List
3021 3021 \labelwidthstring 00.00.0000
3022 3022
3023 3023
3024 3024 \family typewriter
3025 3025 \series bold
3026 3026 -[no]deep_reload
3027 3027 \series default
3028 3028 :
3029 3029 \family default
3030 3030 IPython can use the
3031 3031 \family typewriter
3032 3032 deep_reload
3033 3033 \family default
3034 3034 module which reloads changes in modules recursively (it replaces the
3035 3035 \family typewriter
3036 3036 reload()
3037 3037 \family default
3038 3038 function, so you don't need to change anything to use it).
3039 3039
3040 3040 \family typewriter
3041 3041 deep_reload()
3042 3042 \family default
3043 3043 forces a full reload of modules whose code may have changed, which the
3044 3044 default
3045 3045 \family typewriter
3046 3046 reload()
3047 3047 \family default
3048 3048 function does not.
3049 3049 \layout List
3050 3050 \labelwidthstring 00.00.0000
3051 3051
3052 3052 \SpecialChar ~
3053 3053 When deep_reload is off, IPython will use the normal
3054 3054 \family typewriter
3055 3055 reload()
3056 3056 \family default
3057 3057 , but deep_reload will still be available as
3058 3058 \family typewriter
3059 3059 dreload()
3060 3060 \family default
3061 3061 .
3062 3062 This feature is off by default [which means that you have both normal
3063 3063 \family typewriter
3064 3064 reload()
3065 3065 \family default
3066 3066 and
3067 3067 \family typewriter
3068 3068 dreload()
3069 3069 \family default
3070 3070 ].
3071 3071 \layout List
3072 3072 \labelwidthstring 00.00.0000
3073 3073
3074 3074
3075 3075 \family typewriter
3076 3076 \series bold
3077 3077 -editor\SpecialChar ~
3078 3078 <name>
3079 3079 \family default
3080 3080 \series default
3081 3081 : Which editor to use with the
3082 3082 \family typewriter
3083 3083 %edit
3084 3084 \family default
3085 3085 command.
3086 3086 By default, IPython will honor your
3087 3087 \family typewriter
3088 3088 EDITOR
3089 3089 \family default
3090 3090 environment variable (if not set, vi is the Unix default and notepad the
3091 3091 Windows one).
3092 3092 Since this editor is invoked on the fly by IPython and is meant for editing
3093 3093 small code snippets, you may want to use a small, lightweight editor here
3094 3094 (in case your default
3095 3095 \family typewriter
3096 3096 EDITOR
3097 3097 \family default
3098 3098 is something like Emacs).
3099 3099 \layout List
3100 3100 \labelwidthstring 00.00.0000
3101 3101
3102 3102
3103 3103 \family typewriter
3104 3104 \series bold
3105 3105 -ipythondir\SpecialChar ~
3106 3106 <name>
3107 3107 \series default
3108 3108 :
3109 3109 \family default
3110 3110 name of your IPython configuration directory
3111 3111 \family typewriter
3112 3112 IPYTHONDIR
3113 3113 \family default
3114 3114 .
3115 3115 This can also be specified through the environment variable
3116 3116 \family typewriter
3117 3117 IPYTHONDIR
3118 3118 \family default
3119 3119 .
3120 3120 \layout List
3121 3121 \labelwidthstring 00.00.0000
3122 3122
3123 3123
3124 3124 \family typewriter
3125 3125 \series bold
3126 3126 -log|l
3127 3127 \family default
3128 3128 \series default
3129 3129 : generate a log file of all input.
3130 3130 The file is named
3131 3131 \family typewriter
3132 3132 ipython_log.py
3133 3133 \family default
3134 3134 in your current directory (which prevents logs from multiple IPython sessions
3135 3135 from trampling each other).
3136 3136 You can use this to later restore a session by loading your logfile as
3137 3137 a file to be executed with option
3138 3138 \family typewriter
3139 3139 -logplay
3140 3140 \family default
3141 3141 (see below).
3142 3142 \layout List
3143 3143 \labelwidthstring 00.00.0000
3144 3144
3145 3145
3146 3146 \family typewriter
3147 3147 \series bold
3148 3148 -logfile|lf\SpecialChar ~
3149 3149 <name>
3150 3150 \series default
3151 3151 :
3152 3152 \family default
3153 3153 specify the name of your logfile.
3154 3154 \layout List
3155 3155 \labelwidthstring 00.00.0000
3156 3156
3157 3157
3158 3158 \family typewriter
3159 3159 \series bold
3160 3160 -logplay|lp\SpecialChar ~
3161 3161 <name>
3162 3162 \series default
3163 3163 :
3164 3164 \family default
3165 3165 you can replay a previous log.
3166 3166 For restoring a session as close as possible to the state you left it in,
3167 3167 use this option (don't just run the logfile).
3168 3168 With
3169 3169 \family typewriter
3170 3170 -logplay
3171 3171 \family default
3172 3172 , IPython will try to reconstruct the previous working environment in full,
3173 3173 not just execute the commands in the logfile.
3174 3174 \layout List
3175 3175 \labelwidthstring 00.00.0000
3176 3176
3177 3177 \SpecialChar ~
3178 3178 When a session is restored, logging is automatically turned on again with
3179 3179 the name of the logfile it was invoked with (it is read from the log header).
3180 3180 So once you've turned logging on for a session, you can quit IPython and
3181 3181 reload it as many times as you want and it will continue to log its history
3182 3182 and restore from the beginning every time.
3183 3183 \layout List
3184 3184 \labelwidthstring 00.00.0000
3185 3185
3186 3186 \SpecialChar ~
3187 3187 Caveats: there are limitations in this option.
3188 3188 The history variables
3189 3189 \family typewriter
3190 3190 _i*
3191 3191 \family default
3192 3192 ,
3193 3193 \family typewriter
3194 3194 _*
3195 3195 \family default
3196 3196 and
3197 3197 \family typewriter
3198 3198 _dh
3199 3199 \family default
3200 3200 don't get restored properly.
3201 3201 In the future we will try to implement full session saving by writing and
3202 3202 retrieving a 'snapshot' of the memory state of IPython.
3203 3203 But our first attempts failed because of inherent limitations of Python's
3204 3204 Pickle module, so this may have to wait.
3205 3205 \layout List
3206 3206 \labelwidthstring 00.00.0000
3207 3207
3208 3208
3209 3209 \family typewriter
3210 3210 \series bold
3211 3211 -[no]messages
3212 3212 \series default
3213 3213 :
3214 3214 \family default
3215 3215 Print messages which IPython collects about its startup process (default
3216 3216 on).
3217 3217 \layout List
3218 3218 \labelwidthstring 00.00.0000
3219 3219
3220 3220
3221 3221 \family typewriter
3222 3222 \series bold
3223 3223 -[no]pdb
3224 3224 \family default
3225 3225 \series default
3226 3226 : Automatically call the pdb debugger after every uncaught exception.
3227 3227 If you are used to debugging using pdb, this puts you automatically inside
3228 3228 of it after any call (either in IPython or in code called by it) which
3229 3229 triggers an exception which goes uncaught.
3230 3230 \layout List
3231 3231 \labelwidthstring 00.00.0000
3232 3232
3233 3233
3234 3234 \family typewriter
3235 3235 \series bold
3236 3236 -[no]pprint
3237 3237 \series default
3238 3238 :
3239 3239 \family default
3240 3240 ipython can optionally use the pprint (pretty printer) module for displaying
3241 3241 results.
3242 3242 pprint tends to give a nicer display of nested data structures.
3243 3243 If you like it, you can turn it on permanently in your config file (default
3244 3244 off).
3245 3245 \layout List
3246 3246 \labelwidthstring 00.00.0000
3247 3247
3248 3248
3249 3249 \family typewriter
3250 3250 \series bold
3251 3251 -profile|p <name>
3252 3252 \series default
3253 3253 :
3254 3254 \family default
3255 3255 assume that your config file is
3256 3256 \family typewriter
3257 3257 ipythonrc-<name>
3258 3258 \family default
3259 3259 (looks in current dir first, then in
3260 3260 \family typewriter
3261 3261 IPYTHONDIR
3262 3262 \family default
3263 3263 ).
3264 3264 This is a quick way to keep and load multiple config files for different
3265 3265 tasks, especially if you use the include option of config files.
3266 3266 You can keep a basic
3267 3267 \family typewriter
3268 3268 IPYTHONDIR/ipythonrc
3269 3269 \family default
3270 3270 file and then have other 'profiles' which include this one and load extra
3271 3271 things for particular tasks.
3272 3272 For example:
3273 3273 \layout List
3274 3274 \labelwidthstring 00.00.0000
3275 3275
3276 3276
3277 3277 \family typewriter
3278 3278 \SpecialChar ~
3279 3279
3280 3280 \family default
3281 3281 1.
3282 3282
3283 3283 \family typewriter
3284 3284 $HOME/.ipython/ipythonrc
3285 3285 \family default
3286 3286 : load basic things you always want.
3287 3287 \layout List
3288 3288 \labelwidthstring 00.00.0000
3289 3289
3290 3290
3291 3291 \family typewriter
3292 3292 \SpecialChar ~
3293 3293
3294 3294 \family default
3295 3295 2.
3296 3296
3297 3297 \family typewriter
3298 3298 $HOME/.ipython/ipythonrc-math
3299 3299 \family default
3300 3300 : load (1) and basic math-related modules.
3301 3301
3302 3302 \layout List
3303 3303 \labelwidthstring 00.00.0000
3304 3304
3305 3305
3306 3306 \family typewriter
3307 3307 \SpecialChar ~
3308 3308
3309 3309 \family default
3310 3310 3.
3311 3311
3312 3312 \family typewriter
3313 3313 $HOME/.ipython/ipythonrc-numeric
3314 3314 \family default
3315 3315 : load (1) and Numeric and plotting modules.
3316 3316 \layout List
3317 3317 \labelwidthstring 00.00.0000
3318 3318
3319 3319 \SpecialChar ~
3320 3320 Since it is possible to create an endless loop by having circular file
3321 3321 inclusions, IPython will stop if it reaches 15 recursive inclusions.
3322 3322 \layout List
3323 3323 \labelwidthstring 00.00.0000
3324 3324
3325 3325
3326 3326 \family typewriter
3327 3327 \series bold
3328 3328 -prompt_in1|pi1\SpecialChar ~
3329 3329 <string>:
3330 3330 \family default
3331 3331 \series default
3332 3332 Specify the string used for input prompts.
3333 3333 Note that if you are using numbered prompts, the number is represented
3334 3334 with a '
3335 3335 \backslash
3336 3336 #' in the string.
3337 3337 Don't forget to quote strings with spaces embedded in them.
3338 3338 Default: '
3339 3339 \family typewriter
3340 3340 In\SpecialChar ~
3341 3341 [
3342 3342 \backslash
3343 3343 #]:
3344 3344 \family default
3345 3345 '.
3346 3346 Sec.\SpecialChar ~
3347 3347
3348 3348 \begin_inset LatexCommand \ref{sec:prompts}
3349 3349
3350 3350 \end_inset
3351 3351
3352 3352 discusses in detail all the available escapes to customize your prompts.
3353 3353 \layout List
3354 3354 \labelwidthstring 00.00.0000
3355 3355
3356 3356
3357 3357 \family typewriter
3358 3358 \series bold
3359 3359 -prompt_in2|pi2\SpecialChar ~
3360 3360 <string>:
3361 3361 \family default
3362 3362 \series default
3363 3363 Similar to the previous option, but used for the continuation prompts.
3364 3364 The special sequence '
3365 3365 \family typewriter
3366 3366
3367 3367 \backslash
3368 3368 D
3369 3369 \family default
3370 3370 ' is similar to '
3371 3371 \family typewriter
3372 3372
3373 3373 \backslash
3374 3374 #
3375 3375 \family default
3376 3376 ', but with all digits replaced dots (so you can have your continuation
3377 3377 prompt aligned with your input prompt).
3378 3378 Default: '
3379 3379 \family typewriter
3380 3380 \SpecialChar ~
3381 3381 \SpecialChar ~
3382 3382 \SpecialChar ~
3383 3383 .
3384 3384 \backslash
3385 3385 D.:
3386 3386 \family default
3387 3387 ' (note three spaces at the start for alignment with '
3388 3388 \family typewriter
3389 3389 In\SpecialChar ~
3390 3390 [
3391 3391 \backslash
3392 3392 #]
3393 3393 \family default
3394 3394 ').
3395 3395 \layout List
3396 3396 \labelwidthstring 00.00.0000
3397 3397
3398 3398
3399 3399 \family typewriter
3400 3400 \series bold
3401 3401 -prompt_out|po\SpecialChar ~
3402 3402 <string>:
3403 3403 \family default
3404 3404 \series default
3405 3405 String used for output prompts, also uses numbers like
3406 3406 \family typewriter
3407 3407 prompt_in1
3408 3408 \family default
3409 3409 .
3410 3410 Default: '
3411 3411 \family typewriter
3412 3412 Out[
3413 3413 \backslash
3414 3414 #]:
3415 3415 \family default
3416 3416 '
3417 3417 \layout List
3418 3418 \labelwidthstring 00.00.0000
3419 3419
3420 3420
3421 3421 \family typewriter
3422 3422 \series bold
3423 3423 -quick
3424 3424 \family default
3425 3425 \series default
3426 3426 : start in bare bones mode (no config file loaded).
3427 3427 \layout List
3428 3428 \labelwidthstring 00.00.0000
3429 3429
3430 3430
3431 3431 \family typewriter
3432 3432 \series bold
3433 3433 -rcfile\SpecialChar ~
3434 3434 <name>
3435 3435 \series default
3436 3436 :
3437 3437 \family default
3438 3438 name of your IPython resource configuration file.
3439 3439 Normally IPython loads ipythonrc (from current directory) or
3440 3440 \family typewriter
3441 3441 IPYTHONDIR/ipythonrc
3442 3442 \family default
3443 3443 .
3444 3444 \layout List
3445 3445 \labelwidthstring 00.00.0000
3446 3446
3447 3447 \SpecialChar ~
3448 3448 If the loading of your config file fails, IPython starts with a bare bones
3449 3449 configuration (no modules loaded at all).
3450 3450 \layout List
3451 3451 \labelwidthstring 00.00.0000
3452 3452
3453 3453
3454 3454 \family typewriter
3455 3455 \series bold
3456 3456 -[no]readline
3457 3457 \family default
3458 3458 \series default
3459 3459 : use the readline library, which is needed to support name completion and
3460 3460 command history, among other things.
3461 3461 It is enabled by default, but may cause problems for users of X/Emacs in
3462 3462 Python comint or shell buffers.
3463 3463 \layout List
3464 3464 \labelwidthstring 00.00.0000
3465 3465
3466 3466 \SpecialChar ~
3467 3467 Note that X/Emacs 'eterm' buffers (opened with
3468 3468 \family typewriter
3469 3469 M-x\SpecialChar ~
3470 3470 term
3471 3471 \family default
3472 3472 ) support IPython's readline and syntax coloring fine, only 'emacs' (
3473 3473 \family typewriter
3474 3474 M-x\SpecialChar ~
3475 3475 shell
3476 3476 \family default
3477 3477 and
3478 3478 \family typewriter
3479 3479 C-c\SpecialChar ~
3480 3480 !
3481 3481 \family default
3482 3482 ) buffers do not.
3483 3483 \layout List
3484 3484 \labelwidthstring 00.00.0000
3485 3485
3486 3486
3487 3487 \family typewriter
3488 3488 \series bold
3489 3489 -screen_length|sl\SpecialChar ~
3490 3490 <n>
3491 3491 \series default
3492 3492 :
3493 3493 \family default
3494 3494 number of lines of your screen.
3495 3495 This is used to control printing of very long strings.
3496 3496 Strings longer than this number of lines will be sent through a pager instead
3497 3497 of directly printed.
3498 3498 \layout List
3499 3499 \labelwidthstring 00.00.0000
3500 3500
3501 3501 \SpecialChar ~
3502 3502 The default value for this is 0, which means IPython will auto-detect your
3503 3503 screen size every time it needs to print certain potentially long strings
3504 3504 (this doesn't change the behavior of the 'print' keyword, it's only triggered
3505 3505 internally).
3506 3506 If for some reason this isn't working well (it needs curses support), specify
3507 3507 it yourself.
3508 3508 Otherwise don't change the default.
3509 3509 \layout List
3510 3510 \labelwidthstring 00.00.0000
3511 3511
3512 3512
3513 3513 \family typewriter
3514 3514 \series bold
3515 3515 -separate_in|si\SpecialChar ~
3516 3516 <string>
3517 3517 \series default
3518 3518 :
3519 3519 \family default
3520 3520 separator before input prompts.
3521 3521 Default: '
3522 3522 \family typewriter
3523 3523
3524 3524 \backslash
3525 3525 n
3526 3526 \family default
3527 3527 '
3528 3528 \layout List
3529 3529 \labelwidthstring 00.00.0000
3530 3530
3531 3531
3532 3532 \family typewriter
3533 3533 \series bold
3534 3534 -separate_out|so\SpecialChar ~
3535 3535 <string>
3536 3536 \family default
3537 3537 \series default
3538 3538 : separator before output prompts.
3539 3539 Default: nothing.
3540 3540 \layout List
3541 3541 \labelwidthstring 00.00.0000
3542 3542
3543 3543
3544 3544 \family typewriter
3545 3545 \series bold
3546 3546 -separate_out2|so2\SpecialChar ~
3547 3547 <string>
3548 3548 \series default
3549 3549 :
3550 3550 \family default
3551 3551 separator after output prompts.
3552 3552 Default: nothing.
3553 3553 \layout List
3554 3554 \labelwidthstring 00.00.0000
3555 3555
3556 3556 \SpecialChar ~
3557 3557 For these three options, use the value 0 to specify no separator.
3558 3558 \layout List
3559 3559 \labelwidthstring 00.00.0000
3560 3560
3561 3561
3562 3562 \family typewriter
3563 3563 \series bold
3564 3564 -nosep
3565 3565 \series default
3566 3566 :
3567 3567 \family default
3568 3568 shorthand for
3569 3569 \family typewriter
3570 3570 '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'
3571 3571 \family default
3572 3572 .
3573 3573 Simply removes all input/output separators.
3574 3574 \layout List
3575 3575 \labelwidthstring 00.00.0000
3576 3576
3577 3577
3578 3578 \family typewriter
3579 3579 \series bold
3580 3580 -upgrade
3581 3581 \family default
3582 3582 \series default
3583 3583 : allows you to upgrade your
3584 3584 \family typewriter
3585 3585 IPYTHONDIR
3586 3586 \family default
3587 3587 configuration when you install a new version of IPython.
3588 3588 Since new versions may include new command line options or example files,
3589 3589 this copies updated ipythonrc-type files.
3590 3590 However, it backs up (with a
3591 3591 \family typewriter
3592 3592 .old
3593 3593 \family default
3594 3594 extension) all files which it overwrites so that you can merge back any
3595 3595 customizations you might have in your personal files.
3596 3596 \layout List
3597 3597 \labelwidthstring 00.00.0000
3598 3598
3599 3599
3600 3600 \family typewriter
3601 3601 \series bold
3602 3602 -Version
3603 3603 \series default
3604 3604 :
3605 3605 \family default
3606 3606 print version information and exit.
3607 3607 \layout List
3608 3608 \labelwidthstring 00.00.0000
3609 3609
3610 3610
3611 3611 \family typewriter
3612 3612 \series bold
3613 3613 -wxversion\SpecialChar ~
3614 3614 <string>:
3615 3615 \family default
3616 3616 \series default
3617 3617 Select a specific version of wxPython (used in conjunction with
3618 3618 \family typewriter
3619 3619 -wthread
3620 3620 \family default
3621 3621 ).
3622 3622 Requires the wxversion module, part of recent wxPython distributions
3623 3623 \layout List
3624 3624 \labelwidthstring 00.00.0000
3625 3625
3626 3626
3627 3627 \family typewriter
3628 3628 \series bold
3629 3629 -xmode\SpecialChar ~
3630 3630 <modename>
3631 3631 \series default
3632 3632 :
3633 3633 \family default
3634 3634 Mode for exception reporting.
3635 3635 \layout List
3636 3636 \labelwidthstring 00.00.0000
3637 3637
3638 3638 \SpecialChar ~
3639 3639 Valid modes: Plain, Context and Verbose.
3640 3640 \layout List
3641 3641 \labelwidthstring 00.00.0000
3642 3642
3643 3643 \SpecialChar ~
3644 3644 Plain: similar to python's normal traceback printing.
3645 3645 \layout List
3646 3646 \labelwidthstring 00.00.0000
3647 3647
3648 3648 \SpecialChar ~
3649 3649 Context: prints 5 lines of context source code around each line in the
3650 3650 traceback.
3651 3651 \layout List
3652 3652 \labelwidthstring 00.00.0000
3653 3653
3654 3654 \SpecialChar ~
3655 3655 Verbose: similar to Context, but additionally prints the variables currently
3656 3656 visible where the exception happened (shortening their strings if too long).
3657 3657 This can potentially be very slow, if you happen to have a huge data structure
3658 3658 whose string representation is complex to compute.
3659 3659 Your computer may appear to freeze for a while with cpu usage at 100%.
3660 3660 If this occurs, you can cancel the traceback with Ctrl-C (maybe hitting
3661 3661 it more than once).
3662 3662 \layout Section
3663 3663
3664 3664 Interactive use
3665 3665 \layout Standard
3666 3666
3667 3667
3668 3668 \series bold
3669 3669 Warning
3670 3670 \series default
3671 3671 : IPython relies on the existence of a global variable called
3672 3672 \family typewriter
3673 3673 __IP
3674 3674 \family default
3675 3675 which controls the shell itself.
3676 3676 If you redefine
3677 3677 \family typewriter
3678 3678 __IP
3679 3679 \family default
3680 3680 to anything, bizarre behavior will quickly occur.
3681 3681 \layout Standard
3682 3682
3683 3683 Other than the above warning, IPython is meant to work as a drop-in replacement
3684 3684 for the standard interactive interpreter.
3685 3685 As such, any code which is valid python should execute normally under IPython
3686 3686 (cases where this is not true should be reported as bugs).
3687 3687 It does, however, offer many features which are not available at a standard
3688 3688 python prompt.
3689 3689 What follows is a list of these.
3690 3690 \layout Subsection
3691 3691
3692 3692 Caution for Windows users
3693 3693 \layout Standard
3694 3694
3695 3695 Windows, unfortunately, uses the `
3696 3696 \family typewriter
3697 3697
3698 3698 \backslash
3699 3699
3700 3700 \family default
3701 3701 ' character as a path separator.
3702 3702 This is a terrible choice, because `
3703 3703 \family typewriter
3704 3704
3705 3705 \backslash
3706 3706
3707 3707 \family default
3708 3708 ' also represents the escape character in most modern programming languages,
3709 3709 including Python.
3710 3710 For this reason, issuing many of the commands discussed below (especially
3711 3711 magics which affect the filesystem) with `
3712 3712 \family typewriter
3713 3713
3714 3714 \backslash
3715 3715
3716 3716 \family default
3717 3717 ' in them will cause strange errors.
3718 3718 \layout Standard
3719 3719
3720 3720 A partial solution is to use instead the `
3721 3721 \family typewriter
3722 3722 /
3723 3723 \family default
3724 3724 ' character as a path separator, which Windows recognizes in
3725 3725 \emph on
3726 3726 most
3727 3727 \emph default
3728 3728 situations.
3729 3729 However, in Windows commands `
3730 3730 \family typewriter
3731 3731 /
3732 3732 \family default
3733 3733 ' flags options, so you can not use it for the root directory.
3734 3734 This means that paths beginning at the root must be typed in a contrived
3735 3735 manner like:
3736 3736 \newline
3737 3737
3738 3738 \family typewriter
3739 3739 %copy
3740 3740 \backslash
3741 3741 opt/foo/bar.txt
3742 3742 \backslash
3743 3743 tmp
3744 3744 \layout Standard
3745 3745
3746 3746 There is no sensible thing IPython can do to truly work around this flaw
3747 3747 in Windows
3748 3748 \begin_inset Foot
3749 3749 collapsed true
3750 3750
3751 3751 \layout Standard
3752 3752
3753 3753 If anyone comes up with a
3754 3754 \emph on
3755 3755 clean
3756 3756 \emph default
3757 3757 solution which works consistently and does not negatively impact other
3758 3758 platforms at all, I'll gladly accept a patch.
3759 3759 \end_inset
3760 3760
3761 3761 .
3762 3762 \layout Subsection
3763 3763
3764 3764
3765 3765 \begin_inset LatexCommand \label{sec:magic}
3766 3766
3767 3767 \end_inset
3768 3768
3769 3769 Magic command system
3770 3770 \layout Standard
3771 3771
3772 3772 IPython will treat any line whose first character is a
3773 3773 \family typewriter
3774 3774 %
3775 3775 \family default
3776 3776 as a special call to a 'magic' function.
3777 3777 These allow you to control the behavior of IPython itself, plus a lot of
3778 3778 system-type features.
3779 3779 They are all prefixed with a
3780 3780 \family typewriter
3781 3781 %
3782 3782 \family default
3783 3783 character, but parameters are given without parentheses or quotes.
3784 3784 \layout Standard
3785 3785
3786 3786 Example: typing
3787 3787 \family typewriter
3788 3788 '%cd mydir'
3789 3789 \family default
3790 3790 (without the quotes) changes you working directory to
3791 3791 \family typewriter
3792 3792 'mydir'
3793 3793 \family default
3794 3794 , if it exists.
3795 3795 \layout Standard
3796 3796
3797 3797 If you have 'automagic' enabled (in your
3798 3798 \family typewriter
3799 3799 ipythonrc
3800 3800 \family default
3801 3801 file, via the command line option
3802 3802 \family typewriter
3803 3803 -automagic
3804 3804 \family default
3805 3805 or with the
3806 3806 \family typewriter
3807 3807 %automagic
3808 3808 \family default
3809 3809 function), you don't need to type in the
3810 3810 \family typewriter
3811 3811 %
3812 3812 \family default
3813 3813 explicitly.
3814 3814 IPython will scan its internal list of magic functions and call one if
3815 3815 it exists.
3816 3816 With automagic on you can then just type '
3817 3817 \family typewriter
3818 3818 cd mydir
3819 3819 \family default
3820 3820 ' to go to directory '
3821 3821 \family typewriter
3822 3822 mydir
3823 3823 \family default
3824 3824 '.
3825 3825 The automagic system has the lowest possible precedence in name searches,
3826 3826 so defining an identifier with the same name as an existing magic function
3827 3827 will shadow it for automagic use.
3828 3828 You can still access the shadowed magic function by explicitly using the
3829 3829
3830 3830 \family typewriter
3831 3831 %
3832 3832 \family default
3833 3833 character at the beginning of the line.
3834 3834 \layout Standard
3835 3835
3836 3836 An example (with automagic on) should clarify all this:
3837 3837 \layout LyX-Code
3838 3838
3839 3839 In [1]: cd ipython # %cd is called by automagic
3840 3840 \layout LyX-Code
3841 3841
3842 3842 /home/fperez/ipython
3843 3843 \layout LyX-Code
3844 3844
3845 3845 In [2]: cd=1 # now cd is just a variable
3846 3846 \layout LyX-Code
3847 3847
3848 3848 In [3]: cd ..
3849 3849 # and doesn't work as a function anymore
3850 3850 \layout LyX-Code
3851 3851
3852 3852 ------------------------------------------------------------
3853 3853 \layout LyX-Code
3854 3854
3855 3855 File "<console>", line 1
3856 3856 \layout LyX-Code
3857 3857
3858 3858 cd ..
3859 3859 \layout LyX-Code
3860 3860
3861 3861 ^
3862 3862 \layout LyX-Code
3863 3863
3864 3864 SyntaxError: invalid syntax
3865 3865 \layout LyX-Code
3866 3866
3867 3867 \layout LyX-Code
3868 3868
3869 3869 In [4]: %cd ..
3870 3870 # but %cd always works
3871 3871 \layout LyX-Code
3872 3872
3873 3873 /home/fperez
3874 3874 \layout LyX-Code
3875 3875
3876 3876 In [5]: del cd # if you remove the cd variable
3877 3877 \layout LyX-Code
3878 3878
3879 3879 In [6]: cd ipython # automagic can work again
3880 3880 \layout LyX-Code
3881 3881
3882 3882 /home/fperez/ipython
3883 3883 \layout Standard
3884 3884
3885 3885 You can define your own magic functions to extend the system.
3886 3886 The following is a snippet of code which shows how to do it.
3887 3887 It is provided as file
3888 3888 \family typewriter
3889 3889 example-magic.py
3890 3890 \family default
3891 3891 in the examples directory:
3892 3892 \layout Standard
3893 3893
3894 3894
3895 3895 \begin_inset ERT
3896 3896 status Open
3897 3897
3898 3898 \layout Standard
3899 3899
3900 3900 \backslash
3901 3901 codelist{examples/example-magic.py}
3902 3902 \end_inset
3903 3903
3904 3904
3905 3905 \layout Standard
3906 3906
3907 3907 You can also define your own aliased names for magic functions.
3908 3908 In your
3909 3909 \family typewriter
3910 3910 ipythonrc
3911 3911 \family default
3912 3912 file, placing a line like:
3913 3913 \layout Standard
3914 3914
3915 3915
3916 3916 \family typewriter
3917 3917 execute __IP.magic_cl = __IP.magic_clear
3918 3918 \layout Standard
3919 3919
3920 3920 will define
3921 3921 \family typewriter
3922 3922 %cl
3923 3923 \family default
3924 3924 as a new name for
3925 3925 \family typewriter
3926 3926 %clear
3927 3927 \family default
3928 3928 .
3929 3929 \layout Standard
3930 3930
3931 3931 Type
3932 3932 \family typewriter
3933 3933 %magic
3934 3934 \family default
3935 3935 for more information, including a list of all available magic functions
3936 3936 at any time and their docstrings.
3937 3937 You can also type
3938 3938 \family typewriter
3939 3939 %magic_function_name?
3940 3940 \family default
3941 3941 (see sec.
3942 3942
3943 3943 \begin_inset LatexCommand \ref{sec:dyn-object-info}
3944 3944
3945 3945 \end_inset
3946 3946
3947 3947 for information on the
3948 3948 \family typewriter
3949 3949 '?'
3950 3950 \family default
3951 3951 system) to get information about any particular magic function you are
3952 3952 interested in.
3953 3953 \layout Subsubsection
3954 3954
3955 3955 Magic commands
3956 3956 \layout Standard
3957 3957
3958 3958 The rest of this section is automatically generated for each release from
3959 3959 the docstrings in the IPython code.
3960 3960 Therefore the formatting is somewhat minimal, but this method has the advantage
3961 3961 of having information always in sync with the code.
3962 3962 \layout Standard
3963 3963
3964 3964 A list of all the magic commands available in IPython's
3965 3965 \emph on
3966 3966 default
3967 3967 \emph default
3968 3968 installation follows.
3969 3969 This is similar to what you'll see by simply typing
3970 3970 \family typewriter
3971 3971 %magic
3972 3972 \family default
3973 3973 at the prompt, but that will also give you information about magic commands
3974 3974 you may have added as part of your personal customizations.
3975 3975 \layout Standard
3976 3976
3977 3977
3978 3978 \begin_inset Include \input{magic.tex}
3979 3979 preview false
3980 3980
3981 3981 \end_inset
3982 3982
3983 3983
3984 3984 \layout Subsection
3985 3985
3986 3986 Access to the standard Python help
3987 3987 \layout Standard
3988 3988
3989 3989 As of Python 2.1, a help system is available with access to object docstrings
3990 3990 and the Python manuals.
3991 3991 Simply type
3992 3992 \family typewriter
3993 3993 'help'
3994 3994 \family default
3995 3995 (no quotes) to access it.
3996 3996 You can also type
3997 3997 \family typewriter
3998 3998 help(object)
3999 3999 \family default
4000 4000 to obtain information about a given object, and
4001 4001 \family typewriter
4002 4002 help('keyword')
4003 4003 \family default
4004 4004 for information on a keyword.
4005 4005 As noted in sec.
4006 4006
4007 4007 \begin_inset LatexCommand \ref{sec:help-access}
4008 4008
4009 4009 \end_inset
4010 4010
4011 4011 , you need to properly configure your environment variable
4012 4012 \family typewriter
4013 4013 PYTHONDOCS
4014 4014 \family default
4015 4015 for this feature to work correctly.
4016 4016 \layout Subsection
4017 4017
4018 4018
4019 4019 \begin_inset LatexCommand \label{sec:dyn-object-info}
4020 4020
4021 4021 \end_inset
4022 4022
4023 4023 Dynamic object information
4024 4024 \layout Standard
4025 4025
4026 4026 Typing
4027 4027 \family typewriter
4028 4028 ?word
4029 4029 \family default
4030 4030 or
4031 4031 \family typewriter
4032 4032 word?
4033 4033 \family default
4034 4034 prints detailed information about an object.
4035 4035 If certain strings in the object are too long (docstrings, code, etc.) they
4036 4036 get snipped in the center for brevity.
4037 4037 This system gives access variable types and values, full source code for
4038 4038 any object (if available), function prototypes and other useful information.
4039 4039 \layout Standard
4040 4040
4041 4041 Typing
4042 4042 \family typewriter
4043 4043 ??word
4044 4044 \family default
4045 4045 or
4046 4046 \family typewriter
4047 4047 word??
4048 4048 \family default
4049 4049 gives access to the full information without snipping long strings.
4050 4050 Long strings are sent to the screen through the
4051 4051 \family typewriter
4052 4052 less
4053 4053 \family default
4054 4054 pager if longer than the screen and printed otherwise.
4055 4055 On systems lacking the
4056 4056 \family typewriter
4057 4057 less
4058 4058 \family default
4059 4059 command, IPython uses a very basic internal pager.
4060 4060 \layout Standard
4061 4061
4062 4062 The following magic functions are particularly useful for gathering information
4063 4063 about your working environment.
4064 4064 You can get more details by typing
4065 4065 \family typewriter
4066 4066 %magic
4067 4067 \family default
4068 4068 or querying them individually (use
4069 4069 \family typewriter
4070 4070 %function_name?
4071 4071 \family default
4072 4072 with or without the
4073 4073 \family typewriter
4074 4074 %
4075 4075 \family default
4076 4076 ), this is just a summary:
4077 4077 \layout List
4078 4078 \labelwidthstring 00.00.0000
4079 4079
4080 4080
4081 4081 \family typewriter
4082 4082 \series bold
4083 4083 %pdoc\SpecialChar ~
4084 4084 <object>
4085 4085 \family default
4086 4086 \series default
4087 4087 : Print (or run through a pager if too long) the docstring for an object.
4088 4088 If the given object is a class, it will print both the class and the constructo
4089 4089 r docstrings.
4090 4090 \layout List
4091 4091 \labelwidthstring 00.00.0000
4092 4092
4093 4093
4094 4094 \family typewriter
4095 4095 \series bold
4096 4096 %pdef\SpecialChar ~
4097 4097 <object>
4098 4098 \family default
4099 4099 \series default
4100 4100 : Print the definition header for any callable object.
4101 4101 If the object is a class, print the constructor information.
4102 4102 \layout List
4103 4103 \labelwidthstring 00.00.0000
4104 4104
4105 4105
4106 4106 \family typewriter
4107 4107 \series bold
4108 4108 %psource\SpecialChar ~
4109 4109 <object>
4110 4110 \family default
4111 4111 \series default
4112 4112 : Print (or run through a pager if too long) the source code for an object.
4113 4113 \layout List
4114 4114 \labelwidthstring 00.00.0000
4115 4115
4116 4116
4117 4117 \family typewriter
4118 4118 \series bold
4119 4119 %pfile\SpecialChar ~
4120 4120 <object>
4121 4121 \family default
4122 4122 \series default
4123 4123 : Show the entire source file where an object was defined via a pager, opening
4124 4124 it at the line where the object definition begins.
4125 4125 \layout List
4126 4126 \labelwidthstring 00.00.0000
4127 4127
4128 4128
4129 4129 \family typewriter
4130 4130 \series bold
4131 4131 %who/%whos
4132 4132 \family default
4133 4133 \series default
4134 4134 : These functions give information about identifiers you have defined interactiv
4135 4135 ely (not things you loaded or defined in your configuration files).
4136 4136
4137 4137 \family typewriter
4138 4138 %who
4139 4139 \family default
4140 4140 just prints a list of identifiers and
4141 4141 \family typewriter
4142 4142 %whos
4143 4143 \family default
4144 4144 prints a table with some basic details about each identifier.
4145 4145 \layout Standard
4146 4146
4147 4147 Note that the dynamic object information functions (
4148 4148 \family typewriter
4149 4149 ?/??, %pdoc, %pfile, %pdef, %psource
4150 4150 \family default
4151 4151 ) give you access to documentation even on things which are not really defined
4152 4152 as separate identifiers.
4153 4153 Try for example typing
4154 4154 \family typewriter
4155 4155 {}.get?
4156 4156 \family default
4157 4157 or after doing
4158 4158 \family typewriter
4159 4159 import os
4160 4160 \family default
4161 4161 , type
4162 4162 \family typewriter
4163 4163 os.path.abspath??
4164 4164 \family default
4165 4165 .
4166 4166 \layout Subsection
4167 4167
4168 4168
4169 4169 \begin_inset LatexCommand \label{sec:readline}
4170 4170
4171 4171 \end_inset
4172 4172
4173 4173 Readline-based features
4174 4174 \layout Standard
4175 4175
4176 4176 These features require the GNU readline library, so they won't work if your
4177 4177 Python installation lacks readline support.
4178 4178 We will first describe the default behavior IPython uses, and then how
4179 4179 to change it to suit your preferences.
4180 4180 \layout Subsubsection
4181 4181
4182 4182 Command line completion
4183 4183 \layout Standard
4184 4184
4185 4185 At any time, hitting TAB will complete any available python commands or
4186 4186 variable names, and show you a list of the possible completions if there's
4187 4187 no unambiguous one.
4188 4188 It will also complete filenames in the current directory if no python names
4189 4189 match what you've typed so far.
4190 4190 \layout Subsubsection
4191 4191
4192 4192 Search command history
4193 4193 \layout Standard
4194 4194
4195 4195 IPython provides two ways for searching through previous input and thus
4196 4196 reduce the need for repetitive typing:
4197 4197 \layout Enumerate
4198 4198
4199 4199 Start typing, and then use
4200 4200 \family typewriter
4201 4201 Ctrl-p
4202 4202 \family default
4203 4203 (previous,up) and
4204 4204 \family typewriter
4205 4205 Ctrl-n
4206 4206 \family default
4207 4207 (next,down) to search through only the history items that match what you've
4208 4208 typed so far.
4209 4209 If you use
4210 4210 \family typewriter
4211 4211 Ctrl-p/Ctrl-n
4212 4212 \family default
4213 4213 at a blank prompt, they just behave like normal arrow keys.
4214 4214 \layout Enumerate
4215 4215
4216 4216 Hit
4217 4217 \family typewriter
4218 4218 Ctrl-r
4219 4219 \family default
4220 4220 : opens a search prompt.
4221 4221 Begin typing and the system searches your history for lines that contain
4222 4222 what you've typed so far, completing as much as it can.
4223 4223 \layout Subsubsection
4224 4224
4225 4225 Persistent command history across sessions
4226 4226 \layout Standard
4227 4227
4228 4228 IPython will save your input history when it leaves and reload it next time
4229 4229 you restart it.
4230 4230 By default, the history file is named
4231 4231 \family typewriter
4232 4232 $IPYTHONDIR/history
4233 4233 \family default
4234 4234 , but if you've loaded a named profile, '
4235 4235 \family typewriter
4236 4236 -PROFILE_NAME
4237 4237 \family default
4238 4238 ' is appended to the name.
4239 4239 This allows you to keep separate histories related to various tasks: commands
4240 4240 related to numerical work will not be clobbered by a system shell history,
4241 4241 for example.
4242 4242 \layout Subsubsection
4243 4243
4244 4244 Autoindent
4245 4245 \layout Standard
4246 4246
4247 4247 IPython can recognize lines ending in ':' and indent the next line, while
4248 4248 also un-indenting automatically after 'raise' or 'return'.
4249 4249
4250 4250 \layout Standard
4251 4251
4252 4252 This feature uses the readline library, so it will honor your
4253 4253 \family typewriter
4254 4254 ~/.inputrc
4255 4255 \family default
4256 4256 configuration (or whatever file your
4257 4257 \family typewriter
4258 4258 INPUTRC
4259 4259 \family default
4260 4260 variable points to).
4261 4261 Adding the following lines to your
4262 4262 \family typewriter
4263 4263 .inputrc
4264 4264 \family default
4265 4265 file can make indenting/unindenting more convenient (
4266 4266 \family typewriter
4267 4267 M-i
4268 4268 \family default
4269 4269 indents,
4270 4270 \family typewriter
4271 4271 M-u
4272 4272 \family default
4273 4273 unindents):
4274 4274 \layout Standard
4275 4275
4276 4276
4277 4277 \family typewriter
4278 4278 $if Python
4279 4279 \newline
4280 4280 "
4281 4281 \backslash
4282 4282 M-i": "\SpecialChar ~
4283 4283 \SpecialChar ~
4284 4284 \SpecialChar ~
4285 4285 \SpecialChar ~
4286 4286 "
4287 4287 \newline
4288 4288 "
4289 4289 \backslash
4290 4290 M-u": "
4291 4291 \backslash
4292 4292 d
4293 4293 \backslash
4294 4294 d
4295 4295 \backslash
4296 4296 d
4297 4297 \backslash
4298 4298 d"
4299 4299 \newline
4300 4300 $endif
4301 4301 \layout Standard
4302 4302
4303 4303 Note that there are 4 spaces between the quote marks after
4304 4304 \family typewriter
4305 4305 "M-i"
4306 4306 \family default
4307 4307 above.
4308 4308 \layout Standard
4309 4309
4310 4310
4311 4311 \series bold
4312 4312 Warning:
4313 4313 \series default
4314 4314 this feature is ON by default, but it can cause problems with the pasting
4315 4315 of multi-line indented code (the pasted code gets re-indented on each line).
4316 4316 A magic function
4317 4317 \family typewriter
4318 4318 %autoindent
4319 4319 \family default
4320 4320 allows you to toggle it on/off at runtime.
4321 4321 You can also disable it permanently on in your
4322 4322 \family typewriter
4323 4323 ipythonrc
4324 4324 \family default
4325 4325 file (set
4326 4326 \family typewriter
4327 4327 autoindent 0
4328 4328 \family default
4329 4329 ).
4330 4330 \layout Subsubsection
4331 4331
4332 4332 Customizing readline behavior
4333 4333 \layout Standard
4334 4334
4335 4335 All these features are based on the GNU readline library, which has an extremely
4336 4336 customizable interface.
4337 4337 Normally, readline is configured via a file which defines the behavior
4338 4338 of the library; the details of the syntax for this can be found in the
4339 4339 readline documentation available with your system or on the Internet.
4340 4340 IPython doesn't read this file (if it exists) directly, but it does support
4341 4341 passing to readline valid options via a simple interface.
4342 4342 In brief, you can customize readline by setting the following options in
4343 4343 your
4344 4344 \family typewriter
4345 4345 ipythonrc
4346 4346 \family default
4347 4347 configuration file (note that these options can
4348 4348 \emph on
4349 4349 not
4350 4350 \emph default
4351 4351 be specified at the command line):
4352 4352 \layout List
4353 4353 \labelwidthstring 00.00.0000
4354 4354
4355 4355
4356 4356 \family typewriter
4357 4357 \series bold
4358 4358 readline_parse_and_bind:
4359 4359 \family default
4360 4360 \series default
4361 4361 this option can appear as many times as you want, each time defining a
4362 4362 string to be executed via a
4363 4363 \family typewriter
4364 4364 readline.parse_and_bind()
4365 4365 \family default
4366 4366 command.
4367 4367 The syntax for valid commands of this kind can be found by reading the
4368 4368 documentation for the GNU readline library, as these commands are of the
4369 4369 kind which readline accepts in its configuration file.
4370 4370 \layout List
4371 4371 \labelwidthstring 00.00.0000
4372 4372
4373 4373
4374 4374 \family typewriter
4375 4375 \series bold
4376 4376 readline_remove_delims:
4377 4377 \family default
4378 4378 \series default
4379 4379 a string of characters to be removed from the default word-delimiters list
4380 4380 used by readline, so that completions may be performed on strings which
4381 4381 contain them.
4382 4382 Do not change the default value unless you know what you're doing.
4383 4383 \layout List
4384 4384 \labelwidthstring 00.00.0000
4385 4385
4386 4386
4387 4387 \family typewriter
4388 4388 \series bold
4389 4389 readline_omit__names
4390 4390 \family default
4391 4391 \series default
4392 4392 : when tab-completion is enabled, hitting
4393 4393 \family typewriter
4394 4394 <tab>
4395 4395 \family default
4396 4396 after a '
4397 4397 \family typewriter
4398 4398 .
4399 4399 \family default
4400 4400 ' in a name will complete all attributes of an object, including all the
4401 4401 special methods whose names include double underscores (like
4402 4402 \family typewriter
4403 4403 __getitem__
4404 4404 \family default
4405 4405 or
4406 4406 \family typewriter
4407 4407 __class__
4408 4408 \family default
4409 4409 ).
4410 4410 If you'd rather not see these names by default, you can set this option
4411 4411 to 1.
4412 4412 Note that even when this option is set, you can still see those names by
4413 4413 explicitly typing a
4414 4414 \family typewriter
4415 4415 _
4416 4416 \family default
4417 4417 after the period and hitting
4418 4418 \family typewriter
4419 4419 <tab>
4420 4420 \family default
4421 4421 : '
4422 4422 \family typewriter
4423 4423 name._<tab>
4424 4424 \family default
4425 4425 ' will always complete attribute names starting with '
4426 4426 \family typewriter
4427 4427 _
4428 4428 \family default
4429 4429 '.
4430 4430 \layout List
4431 4431 \labelwidthstring 00.00.0000
4432 4432
4433 4433 \SpecialChar ~
4434 4434 This option is off by default so that new users see all attributes of any
4435 4435 objects they are dealing with.
4436 4436 \layout Standard
4437 4437
4438 4438 You will find the default values along with a corresponding detailed explanation
4439 4439 in your
4440 4440 \family typewriter
4441 4441 ipythonrc
4442 4442 \family default
4443 4443 file.
4444 4444 \layout Subsection
4445 4445
4446 4446 Session logging and restoring
4447 4447 \layout Standard
4448 4448
4449 4449 You can log all input from a session either by starting IPython with the
4450 4450 command line switches
4451 4451 \family typewriter
4452 4452 -log
4453 4453 \family default
4454 4454 or
4455 4455 \family typewriter
4456 4456 -logfile
4457 4457 \family default
4458 4458 (see sec.
4459 4459
4460 4460 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
4461 4461
4462 4462 \end_inset
4463 4463
4464 4464 )or by activating the logging at any moment with the magic function
4465 4465 \family typewriter
4466 4466 %logstart
4467 4467 \family default
4468 4468 .
4469 4469
4470 4470 \layout Standard
4471 4471
4472 4472 Log files can later be reloaded with the
4473 4473 \family typewriter
4474 4474 -logplay
4475 4475 \family default
4476 4476 option and IPython will attempt to 'replay' the log by executing all the
4477 4477 lines in it, thus restoring the state of a previous session.
4478 4478 This feature is not quite perfect, but can still be useful in many cases.
4479 4479 \layout Standard
4480 4480
4481 4481 The log files can also be used as a way to have a permanent record of any
4482 4482 code you wrote while experimenting.
4483 4483 Log files are regular text files which you can later open in your favorite
4484 4484 text editor to extract code or to 'clean them up' before using them to
4485 4485 replay a session.
4486 4486 \layout Standard
4487 4487
4488 4488 The
4489 4489 \family typewriter
4490 4490 %logstart
4491 4491 \family default
4492 4492 function for activating logging in mid-session is used as follows:
4493 4493 \layout Standard
4494 4494
4495 4495
4496 4496 \family typewriter
4497 4497 %logstart [log_name [log_mode]]
4498 4498 \layout Standard
4499 4499
4500 4500 If no name is given, it defaults to a file named
4501 4501 \family typewriter
4502 4502 'log'
4503 4503 \family default
4504 4504 in your IPYTHONDIR directory, in
4505 4505 \family typewriter
4506 4506 'rotate'
4507 4507 \family default
4508 4508 mode (see below).
4509 4509 \layout Standard
4510 4510
4511 4511 '
4512 4512 \family typewriter
4513 4513 %logstart name
4514 4514 \family default
4515 4515 ' saves to file
4516 4516 \family typewriter
4517 4517 'name'
4518 4518 \family default
4519 4519 in
4520 4520 \family typewriter
4521 4521 'backup'
4522 4522 \family default
4523 4523 mode.
4524 4524 It saves your history up to that point and then continues logging.
4525 4525 \layout Standard
4526 4526
4527 4527
4528 4528 \family typewriter
4529 4529 %logstart
4530 4530 \family default
4531 4531 takes a second optional parameter: logging mode.
4532 4532 This can be one of (note that the modes are given unquoted):
4533 4533 \layout List
4534 4534 \labelwidthstring 00.00.0000
4535 4535
4536 4536
4537 4537 \family typewriter
4538 4538 over
4539 4539 \family default
4540 4540 : overwrite existing
4541 4541 \family typewriter
4542 4542 log_name
4543 4543 \family default
4544 4544 .
4545 4545 \layout List
4546 4546 \labelwidthstring 00.00.0000
4547 4547
4548 4548
4549 4549 \family typewriter
4550 4550 backup
4551 4551 \family default
4552 4552 : rename (if exists) to
4553 4553 \family typewriter
4554 4554 log_name~
4555 4555 \family default
4556 4556 and start
4557 4557 \family typewriter
4558 4558 log_name
4559 4559 \family default
4560 4560 .
4561 4561 \layout List
4562 4562 \labelwidthstring 00.00.0000
4563 4563
4564 4564
4565 4565 \family typewriter
4566 4566 append
4567 4567 \family default
4568 4568 : well, that says it.
4569 4569 \layout List
4570 4570 \labelwidthstring 00.00.0000
4571 4571
4572 4572
4573 4573 \family typewriter
4574 4574 rotate
4575 4575 \family default
4576 4576 : create rotating logs
4577 4577 \family typewriter
4578 4578 log_name
4579 4579 \family default
4580 4580 .
4581 4581 \family typewriter
4582 4582 1~
4583 4583 \family default
4584 4584 ,
4585 4585 \family typewriter
4586 4586 log_name.2~
4587 4587 \family default
4588 4588 , etc.
4589 4589 \layout Standard
4590 4590
4591 4591 The
4592 4592 \family typewriter
4593 4593 %logoff
4594 4594 \family default
4595 4595 and
4596 4596 \family typewriter
4597 4597 %logon
4598 4598 \family default
4599 4599 functions allow you to temporarily stop and resume logging to a file which
4600 4600 had previously been started with
4601 4601 \family typewriter
4602 4602 %logstart
4603 4603 \family default
4604 4604 .
4605 4605 They will fail (with an explanation) if you try to use them before logging
4606 4606 has been started.
4607 4607 \layout Subsection
4608 4608
4609 4609
4610 4610 \begin_inset LatexCommand \label{sub:System-shell-access}
4611 4611
4612 4612 \end_inset
4613 4613
4614 4614 System shell access
4615 4615 \layout Standard
4616 4616
4617 4617 Any input line beginning with a
4618 4618 \family typewriter
4619 4619 !
4620 4620 \family default
4621 4621 character is passed verbatim (minus the
4622 4622 \family typewriter
4623 4623 !
4624 4624 \family default
4625 4625 , of course) to the underlying operating system.
4626 4626 For example, typing
4627 4627 \family typewriter
4628 4628 !ls
4629 4629 \family default
4630 4630 will run
4631 4631 \family typewriter
4632 4632 'ls'
4633 4633 \family default
4634 4634 in the current directory.
4635 4635 \layout Subsubsection
4636 4636
4637 4637 Manual capture of command output
4638 4638 \layout Standard
4639 4639
4640 4640 If the input line begins with
4641 4641 \emph on
4642 4642 two
4643 4643 \emph default
4644 4644 exclamation marks,
4645 4645 \family typewriter
4646 4646 !!
4647 4647 \family default
4648 4648 , the command is executed but its output is captured and returned as a python
4649 4649 list, split on newlines.
4650 4650 Any output sent by the subprocess to standard error is printed separately,
4651 4651 so that the resulting list only captures standard output.
4652 4652 The
4653 4653 \family typewriter
4654 4654 !!
4655 4655 \family default
4656 4656 syntax is a shorthand for the
4657 4657 \family typewriter
4658 4658 %sx
4659 4659 \family default
4660 4660 magic command.
4661 4661 \layout Standard
4662 4662
4663 4663 Finally, the
4664 4664 \family typewriter
4665 4665 %sc
4666 4666 \family default
4667 4667 magic (short for `shell capture') is similar to
4668 4668 \family typewriter
4669 4669 %sx
4670 4670 \family default
4671 4671 , but allowing more fine-grained control of the capture details, and storing
4672 4672 the result directly into a named variable.
4673 4673 \layout Standard
4674 4674
4675 4675 See Sec.\SpecialChar ~
4676 4676
4677 4677 \begin_inset LatexCommand \ref{sec:magic}
4678 4678
4679 4679 \end_inset
4680 4680
4681 4681 for details on the magics
4682 4682 \family typewriter
4683 4683 %sc
4684 4684 \family default
4685 4685 and
4686 4686 \family typewriter
4687 4687 %sx
4688 4688 \family default
4689 4689 , or use IPython's own help (
4690 4690 \family typewriter
4691 4691 sc?
4692 4692 \family default
4693 4693 and
4694 4694 \family typewriter
4695 4695 sx?
4696 4696 \family default
4697 4697 ) for further details.
4698 4698 \layout Standard
4699 4699
4700 4700 IPython also allows you to expand the value of python variables when making
4701 4701 system calls.
4702 4702 Any python variable or expression which you prepend with
4703 4703 \family typewriter
4704 4704 $
4705 4705 \family default
4706 4706 will get expanded before the system call is made.
4707 4707
4708 4708 \layout Standard
4709 4709
4710 4710
4711 4711 \family typewriter
4712 4712 In [1]: pyvar='Hello world'
4713 4713 \newline
4714 4714 In [2]: !echo "A python variable: $pyvar"
4715 4715 \newline
4716 4716 A python variable: Hello world
4717 4717 \layout Standard
4718 4718
4719 4719 If you want the shell to actually see a literal
4720 4720 \family typewriter
4721 4721 $
4722 4722 \family default
4723 4723 , you need to type it twice:
4724 4724 \layout Standard
4725 4725
4726 4726
4727 4727 \family typewriter
4728 4728 In [3]: !echo "A system variable: $$HOME"
4729 4729 \newline
4730 4730 A system variable: /home/fperez
4731 4731 \layout Standard
4732 4732
4733 4733 You can pass arbitrary expressions, though you'll need to delimit them with
4734 4734
4735 4735 \family typewriter
4736 4736 {}
4737 4737 \family default
4738 4738 if there is ambiguity as to the extent of the expression:
4739 4739 \layout Standard
4740 4740
4741 4741
4742 4742 \family typewriter
4743 4743 In [5]: x=10
4744 4744 \newline
4745 4745 In [6]: y=20
4746 4746 \newline
4747 4747 In [13]: !echo $x+y
4748 4748 \newline
4749 4749 10+y
4750 4750 \newline
4751 4751 In [7]: !echo ${x+y}
4752 4752 \newline
4753 4753 30
4754 4754 \layout Standard
4755 4755
4756 4756 Even object attributes can be expanded:
4757 4757 \layout Standard
4758 4758
4759 4759
4760 4760 \family typewriter
4761 4761 In [12]: !echo $sys.argv
4762 4762 \newline
4763 4763 [/home/fperez/usr/bin/ipython]
4764 4764 \layout Subsection
4765 4765
4766 4766 System command aliases
4767 4767 \layout Standard
4768 4768
4769 4769 The
4770 4770 \family typewriter
4771 4771 %alias
4772 4772 \family default
4773 4773 magic function and the
4774 4774 \family typewriter
4775 4775 alias
4776 4776 \family default
4777 4777 option in the
4778 4778 \family typewriter
4779 4779 ipythonrc
4780 4780 \family default
4781 4781 configuration file allow you to define magic functions which are in fact
4782 4782 system shell commands.
4783 4783 These aliases can have parameters.
4784 4784
4785 4785 \layout Standard
4786 4786
4787 4787 '
4788 4788 \family typewriter
4789 4789 %alias alias_name cmd
4790 4790 \family default
4791 4791 ' defines '
4792 4792 \family typewriter
4793 4793 alias_name
4794 4794 \family default
4795 4795 ' as an alias for '
4796 4796 \family typewriter
4797 4797 cmd
4798 4798 \family default
4799 4799 '
4800 4800 \layout Standard
4801 4801
4802 4802 Then, typing '
4803 4803 \family typewriter
4804 4804 %alias_name params
4805 4805 \family default
4806 4806 ' will execute the system command '
4807 4807 \family typewriter
4808 4808 cmd params
4809 4809 \family default
4810 4810 ' (from your underlying operating system).
4811 4811
4812 4812 \layout Standard
4813 4813
4814 4814 You can also define aliases with parameters using
4815 4815 \family typewriter
4816 4816 %s
4817 4817 \family default
4818 4818 specifiers (one per parameter).
4819 4819 The following example defines the
4820 4820 \family typewriter
4821 4821 %parts
4822 4822 \family default
4823 4823 function as an alias to the command '
4824 4824 \family typewriter
4825 4825 echo first %s second %s
4826 4826 \family default
4827 4827 ' where each
4828 4828 \family typewriter
4829 4829 %s
4830 4830 \family default
4831 4831 will be replaced by a positional parameter to the call to
4832 4832 \family typewriter
4833 4833 %parts:
4834 4834 \layout Standard
4835 4835
4836 4836
4837 4837 \family typewriter
4838 4838 In [1]: alias parts echo first %s second %s
4839 4839 \newline
4840 4840 In [2]: %parts A B
4841 4841 \newline
4842 4842 first A second B
4843 4843 \newline
4844 4844 In [3]: %parts A
4845 4845 \newline
4846 4846 Incorrect number of arguments: 2 expected.
4847 4847
4848 4848 \newline
4849 4849 parts is an alias to: 'echo first %s second %s'
4850 4850 \layout Standard
4851 4851
4852 4852 If called with no parameters,
4853 4853 \family typewriter
4854 4854 %alias
4855 4855 \family default
4856 4856 prints the table of currently defined aliases.
4857 4857 \layout Standard
4858 4858
4859 4859 The
4860 4860 \family typewriter
4861 4861 %rehash/rehashx
4862 4862 \family default
4863 4863 magics allow you to load your entire
4864 4864 \family typewriter
4865 4865 $PATH
4866 4866 \family default
4867 4867 as ipython aliases.
4868 4868 See their respective docstrings (or sec.\SpecialChar ~
4869 4869
4870 4870 \begin_inset LatexCommand \ref{sec:magic}
4871 4871
4872 4872 \end_inset
4873 4873
4874 4874 for further details).
4875 4875 \layout Subsection
4876 4876
4877 4877
4878 4878 \begin_inset LatexCommand \label{sec:dreload}
4879 4879
4880 4880 \end_inset
4881 4881
4882 4882 Recursive reload
4883 4883 \layout Standard
4884 4884
4885 4885 The
4886 4886 \family typewriter
4887 4887 %dreload
4888 4888 \family default
4889 4889 command does a recursive reload of a module: changes made to the module
4890 4890 since you imported will actually be available without having to exit.
4891 4891 \layout Subsection
4892 4892
4893 4893 Verbose and colored exception traceback printouts
4894 4894 \layout Standard
4895 4895
4896 4896 IPython provides the option to see very detailed exception tracebacks, which
4897 4897 can be especially useful when debugging large programs.
4898 4898 You can run any Python file with the
4899 4899 \family typewriter
4900 4900 %run
4901 4901 \family default
4902 4902 function to benefit from these detailed tracebacks.
4903 4903 Furthermore, both normal and verbose tracebacks can be colored (if your
4904 4904 terminal supports it) which makes them much easier to parse visually.
4905 4905 \layout Standard
4906 4906
4907 4907 See the magic
4908 4908 \family typewriter
4909 4909 xmode
4910 4910 \family default
4911 4911 and
4912 4912 \family typewriter
4913 4913 colors
4914 4914 \family default
4915 4915 functions for details (just type
4916 4916 \family typewriter
4917 4917 %magic
4918 4918 \family default
4919 4919 ).
4920 4920 \layout Standard
4921 4921
4922 4922 These features are basically a terminal version of Ka-Ping Yee's
4923 4923 \family typewriter
4924 4924 cgitb
4925 4925 \family default
4926 4926 module, now part of the standard Python library.
4927 4927 \layout Subsection
4928 4928
4929 4929
4930 4930 \begin_inset LatexCommand \label{sec:cache_input}
4931 4931
4932 4932 \end_inset
4933 4933
4934 4934 Input caching system
4935 4935 \layout Standard
4936 4936
4937 4937 IPython offers numbered prompts (In/Out) with input and output caching.
4938 4938 All input is saved and can be retrieved as variables (besides the usual
4939 4939 arrow key recall).
4940 4940 \layout Standard
4941 4941
4942 4942 The following GLOBAL variables always exist (so don't overwrite them!):
4943 4943
4944 4944 \family typewriter
4945 4945 _i
4946 4946 \family default
4947 4947 : stores previous input.
4948 4948
4949 4949 \family typewriter
4950 4950 _ii
4951 4951 \family default
4952 4952 : next previous.
4953 4953
4954 4954 \family typewriter
4955 4955 _iii
4956 4956 \family default
4957 4957 : next-next previous.
4958 4958
4959 4959 \family typewriter
4960 4960 _ih
4961 4961 \family default
4962 4962 : a list of all input
4963 4963 \family typewriter
4964 4964 _ih[n]
4965 4965 \family default
4966 4966 is the input from line
4967 4967 \family typewriter
4968 4968 n
4969 4969 \family default
4970 4970 and this list is aliased to the global variable
4971 4971 \family typewriter
4972 4972 In
4973 4973 \family default
4974 4974 .
4975 4975 If you overwrite
4976 4976 \family typewriter
4977 4977 In
4978 4978 \family default
4979 4979 with a variable of your own, you can remake the assignment to the internal
4980 4980 list with a simple
4981 4981 \family typewriter
4982 4982 'In=_ih'
4983 4983 \family default
4984 4984 .
4985 4985 \layout Standard
4986 4986
4987 4987 Additionally, global variables named
4988 4988 \family typewriter
4989 4989 _i<n>
4990 4990 \family default
4991 4991 are dynamically created (
4992 4992 \family typewriter
4993 4993 <n>
4994 4994 \family default
4995 4995 being the prompt counter), such that
4996 4996 \newline
4997 4997
4998 4998 \family typewriter
4999 4999 _i<n> == _ih[<n>] == In[<n>].
5000 5000 \layout Standard
5001 5001
5002 5002 For example, what you typed at prompt 14 is available as
5003 5003 \family typewriter
5004 5004 _i14,
5005 5005 \family default
5006 5006
5007 5007 \family typewriter
5008 5008 _ih[14]
5009 5009 \family default
5010 5010 and
5011 5011 \family typewriter
5012 5012 In[14]
5013 5013 \family default
5014 5014 .
5015 5015 \layout Standard
5016 5016
5017 5017 This allows you to easily cut and paste multi line interactive prompts by
5018 5018 printing them out: they print like a clean string, without prompt characters.
5019 5019 You can also manipulate them like regular variables (they are strings),
5020 5020 modify or exec them (typing
5021 5021 \family typewriter
5022 5022 'exec _i9'
5023 5023 \family default
5024 5024 will re-execute the contents of input prompt 9, '
5025 5025 \family typewriter
5026 5026 exec In[9:14]+In[18]
5027 5027 \family default
5028 5028 ' will re-execute lines 9 through 13 and line 18).
5029 5029 \layout Standard
5030 5030
5031 5031 You can also re-execute multiple lines of input easily by using the magic
5032 5032
5033 5033 \family typewriter
5034 5034 %macro
5035 5035 \family default
5036 5036 function (which automates the process and allows re-execution without having
5037 5037 to type '
5038 5038 \family typewriter
5039 5039 exec
5040 5040 \family default
5041 5041 ' every time).
5042 5042 The macro system also allows you to re-execute previous lines which include
5043 5043 magic function calls (which require special processing).
5044 5044 Type
5045 5045 \family typewriter
5046 5046 %macro?
5047 5047 \family default
5048 5048 or see sec.
5049 5049
5050 5050 \begin_inset LatexCommand \ref{sec:magic}
5051 5051
5052 5052 \end_inset
5053 5053
5054 5054 for more details on the macro system.
5055 5055 \layout Standard
5056 5056
5057 5057 A history function
5058 5058 \family typewriter
5059 5059 %hist
5060 5060 \family default
5061 5061 allows you to see any part of your input history by printing a range of
5062 5062 the
5063 5063 \family typewriter
5064 5064 _i
5065 5065 \family default
5066 5066 variables.
5067 5067 \layout Subsection
5068 5068
5069 5069
5070 5070 \begin_inset LatexCommand \label{sec:cache_output}
5071 5071
5072 5072 \end_inset
5073 5073
5074 5074 Output caching system
5075 5075 \layout Standard
5076 5076
5077 5077 For output that is returned from actions, a system similar to the input
5078 5078 cache exists but using
5079 5079 \family typewriter
5080 5080 _
5081 5081 \family default
5082 5082 instead of
5083 5083 \family typewriter
5084 5084 _i
5085 5085 \family default
5086 5086 .
5087 5087 Only actions that produce a result (NOT assignments, for example) are cached.
5088 5088 If you are familiar with Mathematica, IPython's
5089 5089 \family typewriter
5090 5090 _
5091 5091 \family default
5092 5092 variables behave exactly like Mathematica's
5093 5093 \family typewriter
5094 5094 %
5095 5095 \family default
5096 5096 variables.
5097 5097 \layout Standard
5098 5098
5099 5099 The following GLOBAL variables always exist (so don't overwrite them!):
5100 5100
5101 5101 \layout List
5102 5102 \labelwidthstring 00.00.0000
5103 5103
5104 5104
5105 5105 \family typewriter
5106 5106 \series bold
5107 5107 _
5108 5108 \family default
5109 5109 \series default
5110 5110 (a
5111 5111 \emph on
5112 5112 single
5113 5113 \emph default
5114 5114 underscore) : stores previous output, like Python's default interpreter.
5115 5115 \layout List
5116 5116 \labelwidthstring 00.00.0000
5117 5117
5118 5118
5119 5119 \family typewriter
5120 5120 \series bold
5121 5121 __
5122 5122 \family default
5123 5123 \series default
5124 5124 (two underscores): next previous.
5125 5125 \layout List
5126 5126 \labelwidthstring 00.00.0000
5127 5127
5128 5128
5129 5129 \family typewriter
5130 5130 \series bold
5131 5131 ___
5132 5132 \family default
5133 5133 \series default
5134 5134 (three underscores): next-next previous.
5135 5135 \layout Standard
5136 5136
5137 5137 Additionally, global variables named
5138 5138 \family typewriter
5139 5139 _<n>
5140 5140 \family default
5141 5141 are dynamically created (
5142 5142 \family typewriter
5143 5143 <n>
5144 5144 \family default
5145 5145 being the prompt counter), such that the result of output
5146 5146 \family typewriter
5147 5147 <n>
5148 5148 \family default
5149 5149 is always available as
5150 5150 \family typewriter
5151 5151 _<n>
5152 5152 \family default
5153 5153 (don't use the angle brackets, just the number, e.g.
5154 5154
5155 5155 \family typewriter
5156 5156 _21
5157 5157 \family default
5158 5158 ).
5159 5159 \layout Standard
5160 5160
5161 5161 These global variables are all stored in a global dictionary (not a list,
5162 5162 since it only has entries for lines which returned a result) available
5163 5163 under the names
5164 5164 \family typewriter
5165 5165 _oh
5166 5166 \family default
5167 5167 and
5168 5168 \family typewriter
5169 5169 Out
5170 5170 \family default
5171 5171 (similar to
5172 5172 \family typewriter
5173 5173 _ih
5174 5174 \family default
5175 5175 and
5176 5176 \family typewriter
5177 5177 In
5178 5178 \family default
5179 5179 ).
5180 5180 So the output from line 12 can be obtained as
5181 5181 \family typewriter
5182 5182 _12
5183 5183 \family default
5184 5184 ,
5185 5185 \family typewriter
5186 5186 Out[12]
5187 5187 \family default
5188 5188 or
5189 5189 \family typewriter
5190 5190 _oh[12]
5191 5191 \family default
5192 5192 .
5193 5193 If you accidentally overwrite the
5194 5194 \family typewriter
5195 5195 Out
5196 5196 \family default
5197 5197 variable you can recover it by typing
5198 5198 \family typewriter
5199 5199 'Out=_oh
5200 5200 \family default
5201 5201 ' at the prompt.
5202 5202 \layout Standard
5203 5203
5204 5204 This system obviously can potentially put heavy memory demands on your system,
5205 5205 since it prevents Python's garbage collector from removing any previously
5206 5206 computed results.
5207 5207 You can control how many results are kept in memory with the option (at
5208 5208 the command line or in your
5209 5209 \family typewriter
5210 5210 ipythonrc
5211 5211 \family default
5212 5212 file)
5213 5213 \family typewriter
5214 5214 cache_size
5215 5215 \family default
5216 5216 .
5217 5217 If you set it to 0, the whole system is completely disabled and the prompts
5218 5218 revert to the classic
5219 5219 \family typewriter
5220 5220 '>>>'
5221 5221 \family default
5222 5222 of normal Python.
5223 5223 \layout Subsection
5224 5224
5225 5225 Directory history
5226 5226 \layout Standard
5227 5227
5228 5228 Your history of visited directories is kept in the global list
5229 5229 \family typewriter
5230 5230 _dh
5231 5231 \family default
5232 5232 , and the magic
5233 5233 \family typewriter
5234 5234 %cd
5235 5235 \family default
5236 5236 command can be used to go to any entry in that list.
5237 5237 The
5238 5238 \family typewriter
5239 5239 %dhist
5240 5240 \family default
5241 5241 command allows you to view this history.
5242 5242 \layout Subsection
5243 5243
5244 5244 Automatic parentheses and quotes
5245 5245 \layout Standard
5246 5246
5247 5247 These features were adapted from Nathan Gray's LazyPython.
5248 5248 They are meant to allow less typing for common situations.
5249 5249 \layout Subsubsection
5250 5250
5251 5251 Automatic parentheses
5252 5252 \layout Standard
5253 5253
5254 5254 Callable objects (i.e.
5255 5255 functions, methods, etc) can be invoked like this (notice the commas between
5256 5256 the arguments):
5257 5257 \layout Standard
5258 5258
5259 5259
5260 5260 \family typewriter
5261 5261 >>> callable_ob arg1, arg2, arg3
5262 5262 \layout Standard
5263 5263
5264 5264 and the input will be translated to this:
5265 5265 \layout Standard
5266 5266
5267 5267
5268 5268 \family typewriter
5269 5269 --> callable_ob(arg1, arg2, arg3)
5270 5270 \layout Standard
5271 5271
5272 5272 You can force automatic parentheses by using '/' as the first character
5273 5273 of a line.
5274 5274 For example:
5275 5275 \layout Standard
5276 5276
5277 5277
5278 5278 \family typewriter
5279 5279 >>> /globals # becomes 'globals()'
5280 5280 \layout Standard
5281 5281
5282 5282 Note that the '/' MUST be the first character on the line! This won't work:
5283 5283
5284 5284 \layout Standard
5285 5285
5286 5286
5287 5287 \family typewriter
5288 5288 >>> print /globals # syntax error
5289 5289 \layout Standard
5290 5290
5291 5291 In most cases the automatic algorithm should work, so you should rarely
5292 5292 need to explicitly invoke /.
5293 5293 One notable exception is if you are trying to call a function with a list
5294 5294 of tuples as arguments (the parenthesis will confuse IPython):
5295 5295 \layout Standard
5296 5296
5297 5297
5298 5298 \family typewriter
5299 5299 In [1]: zip (1,2,3),(4,5,6) # won't work
5300 5300 \layout Standard
5301 5301
5302 5302 but this will work:
5303 5303 \layout Standard
5304 5304
5305 5305
5306 5306 \family typewriter
5307 5307 In [2]: /zip (1,2,3),(4,5,6)
5308 5308 \newline
5309 5309 ------> zip ((1,2,3),(4,5,6))
5310 5310 \newline
5311 5311 Out[2]= [(1, 4), (2, 5), (3, 6)]
5312 5312 \layout Standard
5313 5313
5314 5314 IPython tells you that it has altered your command line by displaying the
5315 5315 new command line preceded by
5316 5316 \family typewriter
5317 5317 -->
5318 5318 \family default
5319 5319 .
5320 5320 e.g.:
5321 5321 \layout Standard
5322 5322
5323 5323
5324 5324 \family typewriter
5325 5325 In [18]: callable list
5326 5326 \newline
5327 5327 -------> callable (list)
5328 5328 \layout Subsubsection
5329 5329
5330 5330 Automatic quoting
5331 5331 \layout Standard
5332 5332
5333 5333 You can force automatic quoting of a function's arguments by using
5334 5334 \family typewriter
5335 5335 `,'
5336 5336 \family default
5337 5337 or
5338 5338 \family typewriter
5339 5339 `;'
5340 5340 \family default
5341 5341 as the first character of a line.
5342 5342 For example:
5343 5343 \layout Standard
5344 5344
5345 5345
5346 5346 \family typewriter
5347 5347 >>> ,my_function /home/me # becomes my_function("/home/me")
5348 5348 \layout Standard
5349 5349
5350 5350 If you use
5351 5351 \family typewriter
5352 5352 `;'
5353 5353 \family default
5354 5354 instead, the whole argument is quoted as a single string (while
5355 5355 \family typewriter
5356 5356 `,'
5357 5357 \family default
5358 5358 splits on whitespace):
5359 5359 \layout Standard
5360 5360
5361 5361
5362 5362 \family typewriter
5363 5363 >>> ,my_function a b c # becomes my_function("a","b","c")
5364 5364 \layout Standard
5365 5365
5366 5366
5367 5367 \family typewriter
5368 5368 >>> ;my_function a b c # becomes my_function("a b c")
5369 5369 \layout Standard
5370 5370
5371 5371 Note that the `
5372 5372 \family typewriter
5373 5373 ,
5374 5374 \family default
5375 5375 ' or `
5376 5376 \family typewriter
5377 5377 ;
5378 5378 \family default
5379 5379 ' MUST be the first character on the line! This won't work:
5380 5380 \layout Standard
5381 5381
5382 5382
5383 5383 \family typewriter
5384 5384 >>> x = ,my_function /home/me # syntax error
5385 5385 \layout Section
5386 5386
5387 5387
5388 5388 \begin_inset LatexCommand \label{sec:customization}
5389 5389
5390 5390 \end_inset
5391 5391
5392 5392 Customization
5393 5393 \layout Standard
5394 5394
5395 5395 As we've already mentioned, IPython reads a configuration file which can
5396 5396 be specified at the command line (
5397 5397 \family typewriter
5398 5398 -rcfile
5399 5399 \family default
5400 5400 ) or which by default is assumed to be called
5401 5401 \family typewriter
5402 5402 ipythonrc
5403 5403 \family default
5404 5404 .
5405 5405 Such a file is looked for in the current directory where IPython is started
5406 5406 and then in your
5407 5407 \family typewriter
5408 5408 IPYTHONDIR
5409 5409 \family default
5410 5410 , which allows you to have local configuration files for specific projects.
5411 5411 In this section we will call these types of configuration files simply
5412 5412 rcfiles (short for resource configuration file).
5413 5413 \layout Standard
5414 5414
5415 5415 The syntax of an rcfile is one of key-value pairs separated by whitespace,
5416 5416 one per line.
5417 5417 Lines beginning with a
5418 5418 \family typewriter
5419 5419 #
5420 5420 \family default
5421 5421 are ignored as comments, but comments can
5422 5422 \series bold
5423 5423 not
5424 5424 \series default
5425 5425 be put on lines with data (the parser is fairly primitive).
5426 5426 Note that these are not python files, and this is deliberate, because it
5427 5427 allows us to do some things which would be quite tricky to implement if
5428 5428 they were normal python files.
5429 5429 \layout Standard
5430 5430
5431 5431 First, an rcfile can contain permanent default values for almost all command
5432 5432 line options (except things like
5433 5433 \family typewriter
5434 5434 -help
5435 5435 \family default
5436 5436 or
5437 5437 \family typewriter
5438 5438 -Version
5439 5439 \family default
5440 5440 ).
5441 5441 Sec\SpecialChar ~
5442 5442
5443 5443 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
5444 5444
5445 5445 \end_inset
5446 5446
5447 5447 contains a description of all command-line options.
5448 5448 However, values you explicitly specify at the command line override the
5449 5449 values defined in the rcfile.
5450 5450 \layout Standard
5451 5451
5452 5452 Besides command line option values, the rcfile can specify values for certain
5453 5453 extra special options which are not available at the command line.
5454 5454 These options are briefly described below.
5455 5455
5456 5456 \layout Standard
5457 5457
5458 5458 Each of these options may appear as many times as you need it in the file.
5459 5459 \layout List
5460 5460 \labelwidthstring 00.00.0000
5461 5461
5462 5462
5463 5463 \family typewriter
5464 5464 \series bold
5465 5465 include\SpecialChar ~
5466 5466 <file1>\SpecialChar ~
5467 5467 <file2>\SpecialChar ~
5468 5468 ...
5469 5469 \family default
5470 5470 \series default
5471 5471 : you can name
5472 5472 \emph on
5473 5473 other
5474 5474 \emph default
5475 5475 rcfiles you want to recursively load up to 15 levels (don't use the
5476 5476 \family typewriter
5477 5477 <>
5478 5478 \family default
5479 5479 brackets in your names!).
5480 5480 This feature allows you to define a 'base' rcfile with general options
5481 5481 and special-purpose files which can be loaded only when needed with particular
5482 5482 configuration options.
5483 5483 To make this more convenient, IPython accepts the
5484 5484 \family typewriter
5485 5485 -profile <name>
5486 5486 \family default
5487 5487 option (abbreviates to
5488 5488 \family typewriter
5489 5489 -p <name
5490 5490 \family default
5491 5491 >)
5492 5492 \family typewriter
5493 5493 which
5494 5494 \family default
5495 5495 tells it to look for an rcfile named
5496 5496 \family typewriter
5497 5497 ipythonrc-<name>
5498 5498 \family default
5499 5499 .
5500 5500
5501 5501 \layout List
5502 5502 \labelwidthstring 00.00.0000
5503 5503
5504 5504
5505 5505 \family typewriter
5506 5506 \series bold
5507 5507 import_mod\SpecialChar ~
5508 5508 <mod1>\SpecialChar ~
5509 5509 <mod2>\SpecialChar ~
5510 5510 ...
5511 5511 \family default
5512 5512 \series default
5513 5513 : import modules with '
5514 5514 \family typewriter
5515 5515 import
5516 5516 \family default
5517 5517
5518 5518 \family typewriter
5519 5519 <mod1>,<mod2>,...
5520 5520 \family default
5521 5521 '
5522 5522 \layout List
5523 5523 \labelwidthstring 00.00.0000
5524 5524
5525 5525
5526 5526 \family typewriter
5527 5527 \series bold
5528 5528 import_some\SpecialChar ~
5529 5529 <mod>\SpecialChar ~
5530 5530 <f1>\SpecialChar ~
5531 5531 <f2>\SpecialChar ~
5532 5532 ...
5533 5533 \family default
5534 5534 \series default
5535 5535 : import functions with '
5536 5536 \family typewriter
5537 5537 from <mod> import
5538 5538 \family default
5539 5539
5540 5540 \family typewriter
5541 5541 <f1>,<f2>,...
5542 5542 \family default
5543 5543 '
5544 5544 \layout List
5545 5545 \labelwidthstring 00.00.0000
5546 5546
5547 5547
5548 5548 \family typewriter
5549 5549 \series bold
5550 5550 import_all\SpecialChar ~
5551 5551 <mod1>\SpecialChar ~
5552 5552 <mod2>\SpecialChar ~
5553 5553 ...
5554 5554 \family default
5555 5555 \series default
5556 5556 : for each module listed import functions with '
5557 5557 \family typewriter
5558 5558 from <mod> import *
5559 5559 \family default
5560 5560 '
5561 5561 \layout List
5562 5562 \labelwidthstring 00.00.0000
5563 5563
5564 5564
5565 5565 \family typewriter
5566 5566 \series bold
5567 5567 execute\SpecialChar ~
5568 5568 <python\SpecialChar ~
5569 5569 code>
5570 5570 \family default
5571 5571 \series default
5572 5572 : give any single-line python code to be executed.
5573 5573 \layout List
5574 5574 \labelwidthstring 00.00.0000
5575 5575
5576 5576
5577 5577 \family typewriter
5578 5578 \series bold
5579 5579 execfile\SpecialChar ~
5580 5580 <filename>
5581 5581 \family default
5582 5582 \series default
5583 5583 : execute the python file given with an '
5584 5584 \family typewriter
5585 5585 execfile(filename)
5586 5586 \family default
5587 5587 ' command.
5588 5588 Username expansion is performed on the given names.
5589 5589 So if you need any amount of extra fancy customization that won't fit in
5590 5590 any of the above 'canned' options, you can just put it in a separate python
5591 5591 file and execute it.
5592 5592 \layout List
5593 5593 \labelwidthstring 00.00.0000
5594 5594
5595 5595
5596 5596 \family typewriter
5597 5597 \series bold
5598 5598 alias\SpecialChar ~
5599 5599 <alias_def>
5600 5600 \family default
5601 5601 \series default
5602 5602 : this is equivalent to calling '
5603 5603 \family typewriter
5604 5604 %alias\SpecialChar ~
5605 5605 <alias_def>
5606 5606 \family default
5607 5607 ' at the IPython command line.
5608 5608 This way, from within IPython you can do common system tasks without having
5609 5609 to exit it or use the
5610 5610 \family typewriter
5611 5611 !
5612 5612 \family default
5613 5613 escape.
5614 5614 IPython isn't meant to be a shell replacement, but it is often very useful
5615 5615 to be able to do things with files while testing code.
5616 5616 This gives you the flexibility to have within IPython any aliases you may
5617 5617 be used to under your normal system shell.
5618 5618 \layout Subsection
5619 5619
5620 5620
5621 5621 \begin_inset LatexCommand \label{sec:ipytonrc-sample}
5622 5622
5623 5623 \end_inset
5624 5624
5625 5625 Sample
5626 5626 \family typewriter
5627 5627 ipythonrc
5628 5628 \family default
5629 5629 file
5630 5630 \layout Standard
5631 5631
5632 5632 The default rcfile, called
5633 5633 \family typewriter
5634 5634 ipythonrc
5635 5635 \family default
5636 5636 and supplied in your
5637 5637 \family typewriter
5638 5638 IPYTHONDIR
5639 5639 \family default
5640 5640 directory contains lots of comments on all of these options.
5641 5641 We reproduce it here for reference:
5642 5642 \layout Standard
5643 5643
5644 5644
5645 5645 \begin_inset ERT
5646 5646 status Open
5647 5647
5648 5648 \layout Standard
5649 5649
5650 5650 \backslash
5651 5651 codelist{../IPython/UserConfig/ipythonrc}
5652 5652 \end_inset
5653 5653
5654 5654
5655 5655 \layout Subsection
5656 5656
5657 5657
5658 5658 \begin_inset LatexCommand \label{sec:prompts}
5659 5659
5660 5660 \end_inset
5661 5661
5662 5662 Fine-tuning your prompt
5663 5663 \layout Standard
5664 5664
5665 5665 IPython's prompts can be customized using a syntax similar to that of the
5666 5666
5667 5667 \family typewriter
5668 5668 bash
5669 5669 \family default
5670 5670 shell.
5671 5671 Many of
5672 5672 \family typewriter
5673 5673 bash
5674 5674 \family default
5675 5675 's escapes are supported, as well as a few additional ones.
5676 5676 We list them below:
5677 5677 \layout Description
5678 5678
5679 5679
5680 5680 \backslash
5681 5681 # the prompt/history count number
5682 5682 \layout Description
5683 5683
5684 5684
5685 5685 \backslash
5686 5686 D the prompt/history count, with the actual digits replaced by dots.
5687 5687 Used mainly in continuation prompts (prompt_in2)
5688 5688 \layout Description
5689 5689
5690 5690
5691 5691 \backslash
5692 5692 w the current working directory
5693 5693 \layout Description
5694 5694
5695 5695
5696 5696 \backslash
5697 5697 W the basename of current working directory
5698 5698 \layout Description
5699 5699
5700 5700
5701 5701 \backslash
5702 5702 X
5703 5703 \emph on
5704 5704 n
5705 5705 \emph default
5706 5706 where
5707 5707 \begin_inset Formula $n=0\ldots5.$
5708 5708 \end_inset
5709 5709
5710 5710 The current working directory, with
5711 5711 \family typewriter
5712 5712 $HOME
5713 5713 \family default
5714 5714 replaced by
5715 5715 \family typewriter
5716 5716 ~
5717 5717 \family default
5718 5718 , and filtered out to contain only
5719 5719 \begin_inset Formula $n$
5720 5720 \end_inset
5721 5721
5722 5722 path elements
5723 5723 \layout Description
5724 5724
5725 5725
5726 5726 \backslash
5727 5727 Y
5728 5728 \emph on
5729 5729 n
5730 5730 \emph default
5731 5731 Similar to
5732 5732 \backslash
5733 5733 X
5734 5734 \emph on
5735 5735 n
5736 5736 \emph default
5737 5737 , but with the
5738 5738 \begin_inset Formula $n+1$
5739 5739 \end_inset
5740 5740
5741 5741 element included if it is
5742 5742 \family typewriter
5743 5743 ~
5744 5744 \family default
5745 5745 (this is similar to the behavior of the %c
5746 5746 \emph on
5747 5747 n
5748 5748 \emph default
5749 5749 escapes in
5750 5750 \family typewriter
5751 5751 tcsh
5752 5752 \family default
5753 5753 )
5754 5754 \layout Description
5755 5755
5756 5756
5757 5757 \backslash
5758 5758 u the username of the current user
5759 5759 \layout Description
5760 5760
5761 5761
5762 5762 \backslash
5763 5763 $ if the effective UID is 0, a #, otherwise a $
5764 5764 \layout Description
5765 5765
5766 5766
5767 5767 \backslash
5768 5768 h the hostname up to the first `.'
5769 5769 \layout Description
5770 5770
5771 5771
5772 5772 \backslash
5773 5773 H the hostname
5774 5774 \layout Description
5775 5775
5776 5776
5777 5777 \backslash
5778 5778 n a newline
5779 5779 \layout Description
5780 5780
5781 5781
5782 5782 \backslash
5783 5783 r a carriage return
5784 5784 \layout Description
5785 5785
5786 5786
5787 5787 \backslash
5788 5788 v IPython version string
5789 5789 \layout Standard
5790 5790
5791 5791 In addition to these, ANSI color escapes can be insterted into the prompts,
5792 5792 as
5793 5793 \family typewriter
5794 5794
5795 5795 \backslash
5796 5796 C_
5797 5797 \emph on
5798 5798 ColorName
5799 5799 \family default
5800 5800 \emph default
5801 5801 .
5802 5802 The list of valid color names is: Black, Blue, Brown, Cyan, DarkGray, Green,
5803 5803 LightBlue, LightCyan, LightGray, LightGreen, LightPurple, LightRed, NoColor,
5804 5804 Normal, Purple, Red, White, Yellow.
5805 5805 \layout Standard
5806 5806
5807 5807 Finally, IPython supports the evaluation of arbitrary expressions in your
5808 5808 prompt string.
5809 5809 The prompt strings are evaluated through the syntax of PEP 215, but basically
5810 5810 you can use
5811 5811 \family typewriter
5812 5812 $x.y
5813 5813 \family default
5814 5814 to expand the value of
5815 5815 \family typewriter
5816 5816 x.y
5817 5817 \family default
5818 5818 , and for more complicated expressions you can use braces:
5819 5819 \family typewriter
5820 5820 ${foo()+x}
5821 5821 \family default
5822 5822 will call function
5823 5823 \family typewriter
5824 5824 foo
5825 5825 \family default
5826 5826 and add to it the value of
5827 5827 \family typewriter
5828 5828 x
5829 5829 \family default
5830 5830 , before putting the result into your prompt.
5831 5831 For example, using
5832 5832 \newline
5833 5833
5834 5834 \family typewriter
5835 5835 prompt_in1 '${commands.getoutput("uptime")}
5836 5836 \backslash
5837 5837 nIn [
5838 5838 \backslash
5839 5839 #]: '
5840 5840 \newline
5841 5841
5842 5842 \family default
5843 5843 will print the result of the uptime command on each prompt (assuming the
5844 5844
5845 5845 \family typewriter
5846 5846 commands
5847 5847 \family default
5848 5848 module has been imported in your
5849 5849 \family typewriter
5850 5850 ipythonrc
5851 5851 \family default
5852 5852 file).
5853 5853 \layout Subsubsection
5854 5854
5855 5855 Prompt examples
5856 5856 \layout Standard
5857 5857
5858 5858 The following options in an ipythonrc file will give you IPython's default
5859 5859 prompts:
5860 5860 \layout Standard
5861 5861
5862 5862
5863 5863 \family typewriter
5864 5864 prompt_in1 'In [
5865 5865 \backslash
5866 5866 #]:'
5867 5867 \newline
5868 5868 prompt_in2 '\SpecialChar ~
5869 5869 \SpecialChar ~
5870 5870 \SpecialChar ~
5871 5871 .
5872 5872 \backslash
5873 5873 D.:'
5874 5874 \newline
5875 5875 prompt_out 'Out[
5876 5876 \backslash
5877 5877 #]:'
5878 5878 \layout Standard
5879 5879
5880 5880 which look like this:
5881 5881 \layout Standard
5882 5882
5883 5883
5884 5884 \family typewriter
5885 5885 In [1]: 1+2
5886 5886 \newline
5887 5887 Out[1]: 3
5888 5888 \layout Standard
5889 5889
5890 5890
5891 5891 \family typewriter
5892 5892 In [2]: for i in (1,2,3):
5893 5893 \newline
5894 5894
5895 5895 \begin_inset ERT
5896 5896 status Collapsed
5897 5897
5898 5898 \layout Standard
5899 5899
5900 5900 \backslash
5901 5901 hspace*{0mm}
5902 5902 \end_inset
5903 5903
5904 5904 \SpecialChar ~
5905 5905 \SpecialChar ~
5906 5906 \SpecialChar ~
5907 5907 ...: \SpecialChar ~
5908 5908 \SpecialChar ~
5909 5909 \SpecialChar ~
5910 5910 \SpecialChar ~
5911 5911 print i,
5912 5912 \newline
5913 5913
5914 5914 \begin_inset ERT
5915 5915 status Collapsed
5916 5916
5917 5917 \layout Standard
5918 5918
5919 5919 \backslash
5920 5920 hspace*{0mm}
5921 5921 \end_inset
5922 5922
5923 5923 \SpecialChar ~
5924 5924 \SpecialChar ~
5925 5925 \SpecialChar ~
5926 5926 ...:
5927 5927 \newline
5928 5928 1 2 3
5929 5929 \layout Standard
5930 5930
5931 5931 These will give you a very colorful prompt with path information:
5932 5932 \layout Standard
5933 5933
5934 5934
5935 5935 \family typewriter
5936 5936 #prompt_in1 '
5937 5937 \backslash
5938 5938 C_Red
5939 5939 \backslash
5940 5940 u
5941 5941 \backslash
5942 5942 C_Blue[
5943 5943 \backslash
5944 5944 C_Cyan
5945 5945 \backslash
5946 5946 Y1
5947 5947 \backslash
5948 5948 C_Blue]
5949 5949 \backslash
5950 5950 C_LightGreen
5951 5951 \backslash
5952 5952 #>'
5953 5953 \newline
5954 5954 prompt_in2 ' ..
5955 5955 \backslash
5956 5956 D>'
5957 5957 \newline
5958 5958 prompt_out '<
5959 5959 \backslash
5960 5960 #>'
5961 5961 \layout Standard
5962 5962
5963 5963 which look like this:
5964 5964 \layout Standard
5965 5965
5966 5966
5967 5967 \family typewriter
5968 5968 \color red
5969 5969 fperez
5970 5970 \color blue
5971 5971 [
5972 5972 \color cyan
5973 5973 ~/ipython
5974 5974 \color blue
5975 5975 ]
5976 5976 \color green
5977 5977 1>
5978 5978 \color default
5979 5979 1+2
5980 5980 \newline
5981 5981
5982 5982 \begin_inset ERT
5983 5983 status Collapsed
5984 5984
5985 5985 \layout Standard
5986 5986
5987 5987 \backslash
5988 5988 hspace*{0mm}
5989 5989 \end_inset
5990 5990
5991 5991 \SpecialChar ~
5992 5992 \SpecialChar ~
5993 5993 \SpecialChar ~
5994 5994 \SpecialChar ~
5995 5995 \SpecialChar ~
5996 5996 \SpecialChar ~
5997 5997 \SpecialChar ~
5998 5998 \SpecialChar ~
5999 5999 \SpecialChar ~
6000 6000 \SpecialChar ~
6001 6001 \SpecialChar ~
6002 6002 \SpecialChar ~
6003 6003 \SpecialChar ~
6004 6004 \SpecialChar ~
6005 6005 \SpecialChar ~
6006 6006 \SpecialChar ~
6007 6007
6008 6008 \color red
6009 6009 <1>
6010 6010 \color default
6011 6011 3
6012 6012 \newline
6013 6013
6014 6014 \color red
6015 6015 fperez
6016 6016 \color blue
6017 6017 [
6018 6018 \color cyan
6019 6019 ~/ipython
6020 6020 \color blue
6021 6021 ]
6022 6022 \color green
6023 6023 2>
6024 6024 \color default
6025 6025 for i in (1,2,3):
6026 6026 \newline
6027 6027
6028 6028 \begin_inset ERT
6029 6029 status Collapsed
6030 6030
6031 6031 \layout Standard
6032 6032
6033 6033 \backslash
6034 6034 hspace*{0mm}
6035 6035 \end_inset
6036 6036
6037 6037 \SpecialChar ~
6038 6038 \SpecialChar ~
6039 6039 \SpecialChar ~
6040 6040 \SpecialChar ~
6041 6041 \SpecialChar ~
6042 6042 \SpecialChar ~
6043 6043 \SpecialChar ~
6044 6044 \SpecialChar ~
6045 6045 \SpecialChar ~
6046 6046 \SpecialChar ~
6047 6047 \SpecialChar ~
6048 6048 \SpecialChar ~
6049 6049 \SpecialChar ~
6050 6050 \SpecialChar ~
6051 6051 \SpecialChar ~
6052 6052
6053 6053 \color green
6054 6054 ...>
6055 6055 \color default
6056 6056 \SpecialChar ~
6057 6057 \SpecialChar ~
6058 6058 \SpecialChar ~
6059 6059 \SpecialChar ~
6060 6060 print i,
6061 6061 \newline
6062 6062
6063 6063 \begin_inset ERT
6064 6064 status Collapsed
6065 6065
6066 6066 \layout Standard
6067 6067
6068 6068 \backslash
6069 6069 hspace*{0mm}
6070 6070 \end_inset
6071 6071
6072 6072 \SpecialChar ~
6073 6073 \SpecialChar ~
6074 6074 \SpecialChar ~
6075 6075 \SpecialChar ~
6076 6076 \SpecialChar ~
6077 6077 \SpecialChar ~
6078 6078 \SpecialChar ~
6079 6079 \SpecialChar ~
6080 6080 \SpecialChar ~
6081 6081 \SpecialChar ~
6082 6082 \SpecialChar ~
6083 6083 \SpecialChar ~
6084 6084 \SpecialChar ~
6085 6085 \SpecialChar ~
6086 6086 \SpecialChar ~
6087 6087
6088 6088 \color green
6089 6089 ...>
6090 6090 \color default
6091 6091
6092 6092 \newline
6093 6093 1 2 3
6094 6094 \layout Standard
6095 6095
6096 6096 The following shows the usage of dynamic expression evaluation:
6097 6097 \layout Subsection
6098 6098
6099 6099
6100 6100 \begin_inset LatexCommand \label{sec:profiles}
6101 6101
6102 6102 \end_inset
6103 6103
6104 6104 IPython profiles
6105 6105 \layout Standard
6106 6106
6107 6107 As we already mentioned, IPython supports the
6108 6108 \family typewriter
6109 6109 -profile
6110 6110 \family default
6111 6111 command-line option (see sec.
6112 6112
6113 6113 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
6114 6114
6115 6115 \end_inset
6116 6116
6117 6117 ).
6118 6118 A profile is nothing more than a particular configuration file like your
6119 6119 basic
6120 6120 \family typewriter
6121 6121 ipythonrc
6122 6122 \family default
6123 6123 one, but with particular customizations for a specific purpose.
6124 6124 When you start IPython with '
6125 6125 \family typewriter
6126 6126 ipython -profile <name>
6127 6127 \family default
6128 6128 ', it assumes that in your
6129 6129 \family typewriter
6130 6130 IPYTHONDIR
6131 6131 \family default
6132 6132 there is a file called
6133 6133 \family typewriter
6134 6134 ipythonrc-<name>
6135 6135 \family default
6136 6136 , and loads it instead of the normal
6137 6137 \family typewriter
6138 6138 ipythonrc
6139 6139 \family default
6140 6140 .
6141 6141 \layout Standard
6142 6142
6143 6143 This system allows you to maintain multiple configurations which load modules,
6144 6144 set options, define functions, etc.
6145 6145 suitable for different tasks and activate them in a very simple manner.
6146 6146 In order to avoid having to repeat all of your basic options (common things
6147 6147 that don't change such as your color preferences, for example), any profile
6148 6148 can include another configuration file.
6149 6149 The most common way to use profiles is then to have each one include your
6150 6150 basic
6151 6151 \family typewriter
6152 6152 ipythonrc
6153 6153 \family default
6154 6154 file as a starting point, and then add further customizations.
6155 6155 \layout Standard
6156 6156
6157 6157 In sections
6158 6158 \begin_inset LatexCommand \ref{sec:syntax-extensions}
6159 6159
6160 6160 \end_inset
6161 6161
6162 6162 and
6163 6163 \begin_inset LatexCommand \ref{sec:Gnuplot}
6164 6164
6165 6165 \end_inset
6166 6166
6167 6167 we discuss some particular profiles which come as part of the standard
6168 6168 IPython distribution.
6169 6169 You may also look in your
6170 6170 \family typewriter
6171 6171 IPYTHONDIR
6172 6172 \family default
6173 6173 directory, any file whose name begins with
6174 6174 \family typewriter
6175 6175 ipythonrc-
6176 6176 \family default
6177 6177 is a profile.
6178 6178 You can use those as examples for further customizations to suit your own
6179 6179 needs.
6180 6180 \layout Section
6181 6181
6182 6182
6183 6183 \begin_inset OptArg
6184 6184 collapsed false
6185 6185
6186 6186 \layout Standard
6187 6187
6188 6188 IPython as default...
6189 6189 \end_inset
6190 6190
6191 6191 IPython as your default Python environment
6192 6192 \layout Standard
6193 6193
6194 6194 Python honors the environment variable
6195 6195 \family typewriter
6196 6196 PYTHONSTARTUP
6197 6197 \family default
6198 6198 and will execute at startup the file referenced by this variable.
6199 6199 If you put at the end of this file the following two lines of code:
6200 6200 \layout Standard
6201 6201
6202 6202
6203 6203 \family typewriter
6204 6204 import IPython
6205 6205 \newline
6206 6206 IPython.Shell.IPShell().mainloop(sys_exit=1)
6207 6207 \layout Standard
6208 6208
6209 6209 then IPython will be your working environment anytime you start Python.
6210 6210 The
6211 6211 \family typewriter
6212 6212 sys_exit=1
6213 6213 \family default
6214 6214 is needed to have IPython issue a call to
6215 6215 \family typewriter
6216 6216 sys.exit()
6217 6217 \family default
6218 6218 when it finishes, otherwise you'll be back at the normal Python '
6219 6219 \family typewriter
6220 6220 >>>
6221 6221 \family default
6222 6222 ' prompt
6223 6223 \begin_inset Foot
6224 6224 collapsed true
6225 6225
6226 6226 \layout Standard
6227 6227
6228 6228 Based on an idea by Holger Krekel.
6229 6229 \end_inset
6230 6230
6231 6231 .
6232 6232 \layout Standard
6233 6233
6234 6234 This is probably useful to developers who manage multiple Python versions
6235 6235 and don't want to have correspondingly multiple IPython versions.
6236 6236 Note that in this mode, there is no way to pass IPython any command-line
6237 6237 options, as those are trapped first by Python itself.
6238 6238 \layout Section
6239 6239
6240 6240
6241 6241 \begin_inset LatexCommand \label{sec:embed}
6242 6242
6243 6243 \end_inset
6244 6244
6245 6245 Embedding IPython
6246 6246 \layout Standard
6247 6247
6248 6248 It is possible to start an IPython instance
6249 6249 \emph on
6250 6250 inside
6251 6251 \emph default
6252 6252 your own Python programs.
6253 6253 This allows you to evaluate dynamically the state of your code, operate
6254 6254 with your variables, analyze them, etc.
6255 6255 Note however that any changes you make to values while in the shell do
6256 6256
6257 6257 \emph on
6258 6258 not
6259 6259 \emph default
6260 6260 propagate back to the running code, so it is safe to modify your values
6261 6261 because you won't break your code in bizarre ways by doing so.
6262 6262 \layout Standard
6263 6263
6264 6264 This feature allows you to easily have a fully functional python environment
6265 6265 for doing object introspection anywhere in your code with a simple function
6266 6266 call.
6267 6267 In some cases a simple print statement is enough, but if you need to do
6268 6268 more detailed analysis of a code fragment this feature can be very valuable.
6269 6269 \layout Standard
6270 6270
6271 6271 It can also be useful in scientific computing situations where it is common
6272 6272 to need to do some automatic, computationally intensive part and then stop
6273 6273 to look at data, plots, etc
6274 6274 \begin_inset Foot
6275 6275 collapsed true
6276 6276
6277 6277 \layout Standard
6278 6278
6279 6279 This functionality was inspired by IDL's combination of the
6280 6280 \family typewriter
6281 6281 stop
6282 6282 \family default
6283 6283 keyword and the
6284 6284 \family typewriter
6285 6285 .continue
6286 6286 \family default
6287 6287 executive command, which I have found very useful in the past, and by a
6288 6288 posting on comp.lang.python by cmkl <cmkleffner-AT-gmx.de> on Dec.
6289 6289 06/01 concerning similar uses of pyrepl.
6290 6290 \end_inset
6291 6291
6292 6292 .
6293 6293 Opening an IPython instance will give you full access to your data and
6294 6294 functions, and you can resume program execution once you are done with
6295 6295 the interactive part (perhaps to stop again later, as many times as needed).
6296 6296 \layout Standard
6297 6297
6298 6298 The following code snippet is the bare minimum you need to include in your
6299 6299 Python programs for this to work (detailed examples follow later):
6300 6300 \layout LyX-Code
6301 6301
6302 6302 from IPython.Shell import IPShellEmbed
6303 6303 \layout LyX-Code
6304 6304
6305 6305 ipshell = IPShellEmbed()
6306 6306 \layout LyX-Code
6307 6307
6308 6308 ipshell() # this call anywhere in your program will start IPython
6309 6309 \layout Standard
6310 6310
6311 6311 You can run embedded instances even in code which is itself being run at
6312 6312 the IPython interactive prompt with '
6313 6313 \family typewriter
6314 6314 %run\SpecialChar ~
6315 6315 <filename>
6316 6316 \family default
6317 6317 '.
6318 6318 Since it's easy to get lost as to where you are (in your top-level IPython
6319 6319 or in your embedded one), it's a good idea in such cases to set the in/out
6320 6320 prompts to something different for the embedded instances.
6321 6321 The code examples below illustrate this.
6322 6322 \layout Standard
6323 6323
6324 6324 You can also have multiple IPython instances in your program and open them
6325 6325 separately, for example with different options for data presentation.
6326 6326 If you close and open the same instance multiple times, its prompt counters
6327 6327 simply continue from each execution to the next.
6328 6328 \layout Standard
6329 6329
6330 6330 Please look at the docstrings in the
6331 6331 \family typewriter
6332 6332 Shell.py
6333 6333 \family default
6334 6334 module for more details on the use of this system.
6335 6335 \layout Standard
6336 6336
6337 6337 The following sample file illustrating how to use the embedding functionality
6338 6338 is provided in the examples directory as
6339 6339 \family typewriter
6340 6340 example-embed.py
6341 6341 \family default
6342 6342 .
6343 6343 It should be fairly self-explanatory:
6344 6344 \layout Standard
6345 6345
6346 6346
6347 6347 \begin_inset ERT
6348 6348 status Open
6349 6349
6350 6350 \layout Standard
6351 6351
6352 6352 \backslash
6353 6353 codelist{examples/example-embed.py}
6354 6354 \end_inset
6355 6355
6356 6356
6357 6357 \layout Standard
6358 6358
6359 6359 Once you understand how the system functions, you can use the following
6360 6360 code fragments in your programs which are ready for cut and paste:
6361 6361 \layout Standard
6362 6362
6363 6363
6364 6364 \begin_inset ERT
6365 6365 status Open
6366 6366
6367 6367 \layout Standard
6368 6368
6369 6369 \backslash
6370 6370 codelist{examples/example-embed-short.py}
6371 6371 \end_inset
6372 6372
6373 6373
6374 6374 \layout Section
6375 6375
6376 6376
6377 6377 \begin_inset LatexCommand \label{sec:using-pdb}
6378 6378
6379 6379 \end_inset
6380 6380
6381 6381 Using the Python debugger (
6382 6382 \family typewriter
6383 6383 pdb
6384 6384 \family default
6385 6385 )
6386 6386 \layout Subsection
6387 6387
6388 6388 Running entire programs via
6389 6389 \family typewriter
6390 6390 pdb
6391 6391 \layout Standard
6392 6392
6393 6393
6394 6394 \family typewriter
6395 6395 pdb
6396 6396 \family default
6397 6397 , the Python debugger, is a powerful interactive debugger which allows you
6398 6398 to step through code, set breakpoints, watch variables, etc.
6399 6399 IPython makes it very easy to start any script under the control of
6400 6400 \family typewriter
6401 6401 pdb
6402 6402 \family default
6403 6403 , regardless of whether you have wrapped it into a
6404 6404 \family typewriter
6405 6405 `main()'
6406 6406 \family default
6407 6407 function or not.
6408 6408 For this, simply type
6409 6409 \family typewriter
6410 6410 `%run -d myscript'
6411 6411 \family default
6412 6412 at an IPython prompt.
6413 6413 See the
6414 6414 \family typewriter
6415 6415 %run
6416 6416 \family default
6417 6417 command's documentation (via
6418 6418 \family typewriter
6419 6419 `%run?'
6420 6420 \family default
6421 6421 or in Sec.\SpecialChar ~
6422 6422
6423 6423 \begin_inset LatexCommand \ref{sec:magic}
6424 6424
6425 6425 \end_inset
6426 6426
6427 6427 ) for more details, including how to control where
6428 6428 \family typewriter
6429 6429 pdb
6430 6430 \family default
6431 6431 will stop execution first.
6432 6432 \layout Standard
6433 6433
6434 6434 For more information on the use of the
6435 6435 \family typewriter
6436 6436 pdb
6437 6437 \family default
6438 6438 debugger, read the included
6439 6439 \family typewriter
6440 6440 pdb.doc
6441 6441 \family default
6442 6442 file (part of the standard Python distribution).
6443 6443 On a stock Linux system it is located at
6444 6444 \family typewriter
6445 6445 /usr/lib/python2.3/pdb.doc
6446 6446 \family default
6447 6447 , but the easiest way to read it is by using the
6448 6448 \family typewriter
6449 6449 help()
6450 6450 \family default
6451 6451 function of the
6452 6452 \family typewriter
6453 6453 pdb
6454 6454 \family default
6455 6455 module as follows (in an IPython prompt):
6456 6456 \layout Standard
6457 6457
6458 6458
6459 6459 \family typewriter
6460 6460 In [1]: import pdb
6461 6461 \newline
6462 6462 In [2]: pdb.help()
6463 6463 \layout Standard
6464 6464
6465 6465 This will load the
6466 6466 \family typewriter
6467 6467 pdb.doc
6468 6468 \family default
6469 6469 document in a file viewer for you automatically.
6470 6470 \layout Subsection
6471 6471
6472 6472 Automatic invocation of
6473 6473 \family typewriter
6474 6474 pdb
6475 6475 \family default
6476 6476 on exceptions
6477 6477 \layout Standard
6478 6478
6479 6479 IPython, if started with the
6480 6480 \family typewriter
6481 6481 -pdb
6482 6482 \family default
6483 6483 option (or if the option is set in your rc file) can call the Python
6484 6484 \family typewriter
6485 6485 pdb
6486 6486 \family default
6487 6487 debugger every time your code triggers an uncaught exception
6488 6488 \begin_inset Foot
6489 6489 collapsed true
6490 6490
6491 6491 \layout Standard
6492 6492
6493 6493 Many thanks to Christopher Hart for the request which prompted adding this
6494 6494 feature to IPython.
6495 6495 \end_inset
6496 6496
6497 6497 .
6498 6498 This feature can also be toggled at any time with the
6499 6499 \family typewriter
6500 6500 %pdb
6501 6501 \family default
6502 6502 magic command.
6503 6503 This can be extremely useful in order to find the origin of subtle bugs,
6504 6504 because
6505 6505 \family typewriter
6506 6506 pdb
6507 6507 \family default
6508 6508 opens up at the point in your code which triggered the exception, and while
6509 6509 your program is at this point `dead', all the data is still available and
6510 6510 you can walk up and down the stack frame and understand the origin of the
6511 6511 problem.
6512 6512 \layout Standard
6513 6513
6514 6514 Furthermore, you can use these debugging facilities both with the embedded
6515 6515 IPython mode and without IPython at all.
6516 6516 For an embedded shell (see sec.
6517 6517
6518 6518 \begin_inset LatexCommand \ref{sec:embed}
6519 6519
6520 6520 \end_inset
6521 6521
6522 6522 ), simply call the constructor with
6523 6523 \family typewriter
6524 6524 `-pdb'
6525 6525 \family default
6526 6526 in the argument string and automatically
6527 6527 \family typewriter
6528 6528 pdb
6529 6529 \family default
6530 6530 will be called if an uncaught exception is triggered by your code.
6531 6531
6532 6532 \layout Standard
6533 6533
6534 6534 For stand-alone use of the feature in your programs which do not use IPython
6535 6535 at all, put the following lines toward the top of your `main' routine:
6536 6536 \layout Standard
6537 6537 \align left
6538 6538
6539 6539 \family typewriter
6540 6540 import sys,IPython.ultraTB
6541 6541 \newline
6542 6542 sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbose', color_scheme=`Linux',
6543 6543 call_pdb=1)
6544 6544 \layout Standard
6545 6545
6546 6546 The
6547 6547 \family typewriter
6548 6548 mode
6549 6549 \family default
6550 6550 keyword can be either
6551 6551 \family typewriter
6552 6552 `Verbose'
6553 6553 \family default
6554 6554 or
6555 6555 \family typewriter
6556 6556 `Plain'
6557 6557 \family default
6558 6558 , giving either very detailed or normal tracebacks respectively.
6559 6559 The
6560 6560 \family typewriter
6561 6561 color_scheme
6562 6562 \family default
6563 6563 keyword can be one of
6564 6564 \family typewriter
6565 6565 `NoColor'
6566 6566 \family default
6567 6567 ,
6568 6568 \family typewriter
6569 6569 `Linux'
6570 6570 \family default
6571 6571 (default) or
6572 6572 \family typewriter
6573 6573 `LightBG'
6574 6574 \family default
6575 6575 .
6576 6576 These are the same options which can be set in IPython with
6577 6577 \family typewriter
6578 6578 -colors
6579 6579 \family default
6580 6580 and
6581 6581 \family typewriter
6582 6582 -xmode
6583 6583 \family default
6584 6584 .
6585 6585 \layout Standard
6586 6586
6587 6587 This will give any of your programs detailed, colored tracebacks with automatic
6588 6588 invocation of
6589 6589 \family typewriter
6590 6590 pdb
6591 6591 \family default
6592 6592 .
6593 6593 \layout Section
6594 6594
6595 6595
6596 6596 \begin_inset LatexCommand \label{sec:syntax-extensions}
6597 6597
6598 6598 \end_inset
6599 6599
6600 6600 Extensions for syntax processing
6601 6601 \layout Standard
6602 6602
6603 6603 This isn't for the faint of heart, because the potential for breaking things
6604 6604 is quite high.
6605 6605 But it can be a very powerful and useful feature.
6606 6606 In a nutshell, you can redefine the way IPython processes the user input
6607 6607 line to accept new, special extensions to the syntax without needing to
6608 6608 change any of IPython's own code.
6609 6609 \layout Standard
6610 6610
6611 6611 In the
6612 6612 \family typewriter
6613 6613 IPython/Extensions
6614 6614 \family default
6615 6615 directory you will find some examples supplied, which we will briefly describe
6616 6616 now.
6617 6617 These can be used `as is' (and both provide very useful functionality),
6618 6618 or you can use them as a starting point for writing your own extensions.
6619 6619 \layout Subsection
6620 6620
6621 6621 Pasting of code starting with
6622 6622 \family typewriter
6623 6623 `>>>
6624 6624 \family default
6625 6625 ' or
6626 6626 \family typewriter
6627 6627 `...
6628 6628
6629 6629 \family default
6630 6630 '
6631 6631 \layout Standard
6632 6632
6633 6633 In the python tutorial it is common to find code examples which have been
6634 6634 taken from real python sessions.
6635 6635 The problem with those is that all the lines begin with either
6636 6636 \family typewriter
6637 6637 `>>>
6638 6638 \family default
6639 6639 ' or
6640 6640 \family typewriter
6641 6641 `...
6642 6642
6643 6643 \family default
6644 6644 ', which makes it impossible to paste them all at once.
6645 6645 One must instead do a line by line manual copying, carefully removing the
6646 6646 leading extraneous characters.
6647 6647 \layout Standard
6648 6648
6649 6649 This extension identifies those starting characters and removes them from
6650 6650 the input automatically, so that one can paste multi-line examples directly
6651 6651 into IPython, saving a lot of time.
6652 6652 Please look at the file
6653 6653 \family typewriter
6654 6654 InterpreterPasteInput.py
6655 6655 \family default
6656 6656 in the
6657 6657 \family typewriter
6658 6658 IPython/Extensions
6659 6659 \family default
6660 6660 directory for details on how this is done.
6661 6661 \layout Standard
6662 6662
6663 6663 IPython comes with a special profile enabling this feature, called
6664 6664 \family typewriter
6665 6665 tutorial
6666 6666 \family default
6667 6667 \emph on
6668 6668 .
6669 6669
6670 6670 \emph default
6671 6671 Simply start IPython via
6672 6672 \family typewriter
6673 6673 `ipython\SpecialChar ~
6674 6674 -p\SpecialChar ~
6675 6675 tutorial'
6676 6676 \family default
6677 6677 and the feature will be available.
6678 6678 In a normal IPython session you can activate the feature by importing the
6679 6679 corresponding module with:
6680 6680 \newline
6681 6681
6682 6682 \family typewriter
6683 6683 In [1]: import IPython.Extensions.InterpreterPasteInput
6684 6684 \layout Standard
6685 6685
6686 6686 The following is a 'screenshot' of how things work when this extension is
6687 6687 on, copying an example from the standard tutorial:
6688 6688 \layout Standard
6689 6689
6690 6690
6691 6691 \family typewriter
6692 6692 IPython profile: tutorial
6693 6693 \newline
6694 6694 \SpecialChar ~
6695 6695
6696 6696 \newline
6697 6697 *** Pasting of code with ">>>" or "..." has been enabled.
6698 6698 \newline
6699 6699 \SpecialChar ~
6700 6700
6701 6701 \newline
6702 6702 In [1]: >>> def fib2(n): # return Fibonacci series up to n
6703 6703 \newline
6704 6704
6705 6705 \begin_inset ERT
6706 6706 status Collapsed
6707 6707
6708 6708 \layout Standard
6709 6709
6710 6710 \backslash
6711 6711 hspace*{0mm}
6712 6712 \end_inset
6713 6713
6714 6714 \SpecialChar ~
6715 6715 \SpecialChar ~
6716 6716 ...: ...\SpecialChar ~
6717 6717 \SpecialChar ~
6718 6718 \SpecialChar ~
6719 6719 \SpecialChar ~
6720 6720 """Return a list containing the Fibonacci series up to n."""
6721 6721 \newline
6722 6722
6723 6723 \begin_inset ERT
6724 6724 status Collapsed
6725 6725
6726 6726 \layout Standard
6727 6727
6728 6728 \backslash
6729 6729 hspace*{0mm}
6730 6730 \end_inset
6731 6731
6732 6732 \SpecialChar ~
6733 6733 \SpecialChar ~
6734 6734 ...: ...\SpecialChar ~
6735 6735 \SpecialChar ~
6736 6736 \SpecialChar ~
6737 6737 \SpecialChar ~
6738 6738 result = []
6739 6739 \newline
6740 6740
6741 6741 \begin_inset ERT
6742 6742 status Collapsed
6743 6743
6744 6744 \layout Standard
6745 6745
6746 6746 \backslash
6747 6747 hspace*{0mm}
6748 6748 \end_inset
6749 6749
6750 6750 \SpecialChar ~
6751 6751 \SpecialChar ~
6752 6752 ...: ...\SpecialChar ~
6753 6753 \SpecialChar ~
6754 6754 \SpecialChar ~
6755 6755 \SpecialChar ~
6756 6756 a, b = 0, 1
6757 6757 \newline
6758 6758
6759 6759 \begin_inset ERT
6760 6760 status Collapsed
6761 6761
6762 6762 \layout Standard
6763 6763
6764 6764 \backslash
6765 6765 hspace*{0mm}
6766 6766 \end_inset
6767 6767
6768 6768 \SpecialChar ~
6769 6769 \SpecialChar ~
6770 6770 ...: ...\SpecialChar ~
6771 6771 \SpecialChar ~
6772 6772 \SpecialChar ~
6773 6773 \SpecialChar ~
6774 6774 while b < n:
6775 6775 \newline
6776 6776
6777 6777 \begin_inset ERT
6778 6778 status Collapsed
6779 6779
6780 6780 \layout Standard
6781 6781
6782 6782 \backslash
6783 6783 hspace*{0mm}
6784 6784 \end_inset
6785 6785
6786 6786 \SpecialChar ~
6787 6787 \SpecialChar ~
6788 6788 ...: ...\SpecialChar ~
6789 6789 \SpecialChar ~
6790 6790 \SpecialChar ~
6791 6791 \SpecialChar ~
6792 6792 \SpecialChar ~
6793 6793 \SpecialChar ~
6794 6794 \SpecialChar ~
6795 6795 \SpecialChar ~
6796 6796 result.append(b)\SpecialChar ~
6797 6797 \SpecialChar ~
6798 6798 \SpecialChar ~
6799 6799 # see below
6800 6800 \newline
6801 6801
6802 6802 \begin_inset ERT
6803 6803 status Collapsed
6804 6804
6805 6805 \layout Standard
6806 6806
6807 6807 \backslash
6808 6808 hspace*{0mm}
6809 6809 \end_inset
6810 6810
6811 6811 \SpecialChar ~
6812 6812 \SpecialChar ~
6813 6813 ...: ...\SpecialChar ~
6814 6814 \SpecialChar ~
6815 6815 \SpecialChar ~
6816 6816 \SpecialChar ~
6817 6817 \SpecialChar ~
6818 6818 \SpecialChar ~
6819 6819 \SpecialChar ~
6820 6820 \SpecialChar ~
6821 6821 a, b = b, a+b
6822 6822 \newline
6823 6823
6824 6824 \begin_inset ERT
6825 6825 status Collapsed
6826 6826
6827 6827 \layout Standard
6828 6828
6829 6829 \backslash
6830 6830 hspace*{0mm}
6831 6831 \end_inset
6832 6832
6833 6833 \SpecialChar ~
6834 6834 \SpecialChar ~
6835 6835 ...: ...\SpecialChar ~
6836 6836 \SpecialChar ~
6837 6837 \SpecialChar ~
6838 6838 \SpecialChar ~
6839 6839 return result
6840 6840 \newline
6841 6841
6842 6842 \begin_inset ERT
6843 6843 status Collapsed
6844 6844
6845 6845 \layout Standard
6846 6846
6847 6847 \backslash
6848 6848 hspace*{0mm}
6849 6849 \end_inset
6850 6850
6851 6851 \SpecialChar ~
6852 6852 \SpecialChar ~
6853 6853 ...:
6854 6854 \newline
6855 6855 \SpecialChar ~
6856 6856
6857 6857 \newline
6858 6858 In [2]: fib2(10)
6859 6859 \newline
6860 6860 Out[2]: [1, 1, 2, 3, 5, 8]
6861 6861 \layout Standard
6862 6862
6863 6863 Note that as currently written, this extension does
6864 6864 \emph on
6865 6865 not
6866 6866 \emph default
6867 6867 recognize IPython's prompts for pasting.
6868 6868 Those are more complicated, since the user can change them very easily,
6869 6869 they involve numbers and can vary in length.
6870 6870 One could however extract all the relevant information from the IPython
6871 6871 instance and build an appropriate regular expression.
6872 6872 This is left as an exercise for the reader.
6873 6873 \layout Subsection
6874 6874
6875 6875 Input of physical quantities with units
6876 6876 \layout Standard
6877 6877
6878 6878 The module
6879 6879 \family typewriter
6880 6880 PhysicalQInput
6881 6881 \family default
6882 6882 allows a simplified form of input for physical quantities with units.
6883 6883 This file is meant to be used in conjunction with the
6884 6884 \family typewriter
6885 6885 PhysicalQInteractive
6886 6886 \family default
6887 6887 module (in the same directory) and
6888 6888 \family typewriter
6889 6889 Physics.PhysicalQuantities
6890 6890 \family default
6891 6891 from Konrad Hinsen's ScientificPython (
6892 6892 \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/hinsen/scientific.html}
6893 6893
6894 6894 \end_inset
6895 6895
6896 6896 ).
6897 6897 \layout Standard
6898 6898
6899 6899 The
6900 6900 \family typewriter
6901 6901 Physics.PhysicalQuantities
6902 6902 \family default
6903 6903 module defines
6904 6904 \family typewriter
6905 6905 PhysicalQuantity
6906 6906 \family default
6907 6907 objects, but these must be declared as instances of a class.
6908 6908 For example, to define
6909 6909 \family typewriter
6910 6910 v
6911 6911 \family default
6912 6912 as a velocity of 3\SpecialChar ~
6913 6913 m/s, normally you would write:
6914 6914 \family typewriter
6915 6915
6916 6916 \newline
6917 6917 In [1]: v = PhysicalQuantity(3,'m/s')
6918 6918 \layout Standard
6919 6919
6920 6920 Using the
6921 6921 \family typewriter
6922 6922 PhysicalQ_Input
6923 6923 \family default
6924 6924 extension this can be input instead as:
6925 6925 \family typewriter
6926 6926
6927 6927 \newline
6928 6928 In [1]: v = 3 m/s
6929 6929 \family default
6930 6930
6931 6931 \newline
6932 6932 which is much more convenient for interactive use (even though it is blatantly
6933 6933 invalid Python syntax).
6934 6934 \layout Standard
6935 6935
6936 6936 The
6937 6937 \family typewriter
6938 6938 physics
6939 6939 \family default
6940 6940 profile supplied with IPython (enabled via
6941 6941 \family typewriter
6942 6942 'ipython -p physics'
6943 6943 \family default
6944 6944 ) uses these extensions, which you can also activate with:
6945 6945 \layout Standard
6946 6946
6947 6947
6948 6948 \family typewriter
6949 6949 from math import * # math MUST be imported BEFORE PhysicalQInteractive
6950 6950 \newline
6951 6951 from IPython.Extensions.PhysicalQInteractive import *
6952 6952 \newline
6953 6953 import IPython.Extensions.PhysicalQInput
6954 6954 \layout Section
6955 6955
6956 6956
6957 6957 \begin_inset LatexCommand \label{sec:IPython-as-shell}
6958 6958
6959 6959 \end_inset
6960 6960
6961 6961 IPython as a system shell
6962 6962 \layout Standard
6963 6963
6964 6964 IPython ships with a special profile called
6965 6965 \family typewriter
6966 6966 pysh
6967 6967 \family default
6968 6968 , which you can activate at the command line as
6969 6969 \family typewriter
6970 6970 `ipython -p pysh'
6971 6971 \family default
6972 6972 .
6973 6973 This loads
6974 6974 \family typewriter
6975 6975 InterpreterExec
6976 6976 \family default
6977 6977 , along with some additional facilities and a prompt customized for filesystem
6978 6978 navigation.
6979 6979 \layout Standard
6980 6980
6981 6981 Note that this does
6982 6982 \emph on
6983 6983 not
6984 6984 \emph default
6985 6985 make IPython a full-fledged system shell.
6986 6986 In particular, it has no job control, so if you type Ctrl-Z (under Unix),
6987 6987 you'll suspend pysh itself, not the process you just started.
6988 6988
6989 6989 \layout Standard
6990 6990
6991 6991 What the shell profile allows you to do is to use the convenient and powerful
6992 6992 syntax of Python to do quick scripting at the command line.
6993 6993 Below we describe some of its features.
6994 6994 \layout Subsection
6995 6995
6996 6996 Aliases
6997 6997 \layout Standard
6998 6998
6999 6999 All of your
7000 7000 \family typewriter
7001 7001 $PATH
7002 7002 \family default
7003 7003 has been loaded as IPython aliases, so you should be able to type any normal
7004 7004 system command and have it executed.
7005 7005 See
7006 7006 \family typewriter
7007 7007 %alias?
7008 7008 \family default
7009 7009 and
7010 7010 \family typewriter
7011 7011 %unalias?
7012 7012 \family default
7013 7013 for details on the alias facilities.
7014 7014 See also
7015 7015 \family typewriter
7016 7016 %rehash?
7017 7017 \family default
7018 7018 and
7019 7019 \family typewriter
7020 7020 %rehashx?
7021 7021 \family default
7022 7022 for details on the mechanism used to load
7023 7023 \family typewriter
7024 7024 $PATH
7025 7025 \family default
7026 7026 .
7027 7027 \layout Subsection
7028 7028
7029 7029 Special syntax
7030 7030 \layout Standard
7031 7031
7032 7032 Any lines which begin with
7033 7033 \family typewriter
7034 7034 `~'
7035 7035 \family default
7036 7036 ,
7037 7037 \family typewriter
7038 7038 `/'
7039 7039 \family default
7040 7040 and
7041 7041 \family typewriter
7042 7042 `.'
7043 7043 \family default
7044 7044 will be executed as shell commands instead of as Python code.
7045 7045 The special escapes below are also recognized.
7046 7046
7047 7047 \family typewriter
7048 7048 !cmd
7049 7049 \family default
7050 7050 is valid in single or multi-line input, all others are only valid in single-lin
7051 7051 e input:
7052 7052 \layout Description
7053 7053
7054 7054
7055 7055 \family typewriter
7056 7056 !cmd
7057 7057 \family default
7058 7058 pass `cmd' directly to the shell
7059 7059 \layout Description
7060 7060
7061 7061
7062 7062 \family typewriter
7063 7063 !!cmd
7064 7064 \family default
7065 7065 execute `cmd' and return output as a list (split on `
7066 7066 \backslash
7067 7067 n')
7068 7068 \layout Description
7069 7069
7070 7070
7071 7071 \family typewriter
7072 7072 $var=cmd
7073 7073 \family default
7074 7074 capture output of cmd into var, as a string
7075 7075 \layout Description
7076 7076
7077 7077
7078 7078 \family typewriter
7079 7079 $$var=cmd
7080 7080 \family default
7081 7081 capture output of cmd into var, as a list (split on `
7082 7082 \backslash
7083 7083 n')
7084 7084 \layout Standard
7085 7085
7086 7086 The
7087 7087 \family typewriter
7088 7088 $
7089 7089 \family default
7090 7090 /
7091 7091 \family typewriter
7092 7092 $$
7093 7093 \family default
7094 7094 syntaxes make Python variables from system output, which you can later
7095 7095 use for further scripting.
7096 7096 The converse is also possible: when executing an alias or calling to the
7097 7097 system via
7098 7098 \family typewriter
7099 7099 !
7100 7100 \family default
7101 7101 /
7102 7102 \family typewriter
7103 7103 !!
7104 7104 \family default
7105 7105 , you can expand any python variable or expression by prepending it with
7106 7106
7107 7107 \family typewriter
7108 7108 $
7109 7109 \family default
7110 7110 .
7111 7111 Full details of the allowed syntax can be found in Python's PEP 215.
7112 7112 \layout Standard
7113 7113
7114 7114 A few brief examples will illustrate these (note that the indentation below
7115 7115 may be incorrectly displayed):
7116 7116 \layout Standard
7117 7117
7118 7118
7119 7119 \family typewriter
7120 7120 fperez[~/test]|3> !ls *s.py
7121 7121 \newline
7122 7122 scopes.py strings.py
7123 7123 \layout Standard
7124 7124
7125 7125 ls is an internal alias, so there's no need to use
7126 7126 \family typewriter
7127 7127 !
7128 7128 \family default
7129 7129 :
7130 7130 \layout Standard
7131 7131
7132 7132
7133 7133 \family typewriter
7134 7134 fperez[~/test]|4> ls *s.py
7135 7135 \newline
7136 7136 scopes.py* strings.py
7137 7137 \layout Standard
7138 7138
7139 7139 !!ls will return the output into a Python variable:
7140 7140 \layout Standard
7141 7141
7142 7142
7143 7143 \family typewriter
7144 7144 fperez[~/test]|5> !!ls *s.py
7145 7145 \newline
7146 7146
7147 7147 \begin_inset ERT
7148 7148 status Collapsed
7149 7149
7150 7150 \layout Standard
7151 7151
7152 7152 \backslash
7153 7153 hspace*{0mm}
7154 7154 \end_inset
7155 7155
7156 7156 \SpecialChar ~
7157 7157 \SpecialChar ~
7158 7158 \SpecialChar ~
7159 7159 \SpecialChar ~
7160 7160 \SpecialChar ~
7161 7161 \SpecialChar ~
7162 7162 \SpecialChar ~
7163 7163 \SpecialChar ~
7164 7164 \SpecialChar ~
7165 7165 \SpecialChar ~
7166 7166 \SpecialChar ~
7167 7167 \SpecialChar ~
7168 7168 \SpecialChar ~
7169 7169 \SpecialChar ~
7170 7170 <5> ['scopes.py', 'strings.py']
7171 7171 \newline
7172 7172 fperez[~/test]|6> print _5
7173 7173 \newline
7174 7174 ['scopes.py', 'strings.py']
7175 7175 \layout Standard
7176 7176
7177 7177
7178 7178 \family typewriter
7179 7179 $
7180 7180 \family default
7181 7181 and
7182 7182 \family typewriter
7183 7183 $$
7184 7184 \family default
7185 7185 allow direct capture to named variables:
7186 7186 \layout Standard
7187 7187
7188 7188
7189 7189 \family typewriter
7190 7190 fperez[~/test]|7> $astr = ls *s.py
7191 7191 \newline
7192 7192 fperez[~/test]|8> astr
7193 7193 \newline
7194 7194
7195 7195 \begin_inset ERT
7196 7196 status Collapsed
7197 7197
7198 7198 \layout Standard
7199 7199
7200 7200 \backslash
7201 7201 hspace*{0mm}
7202 7202 \end_inset
7203 7203
7204 7204 \SpecialChar ~
7205 7205 \SpecialChar ~
7206 7206 \SpecialChar ~
7207 7207 \SpecialChar ~
7208 7208 \SpecialChar ~
7209 7209 \SpecialChar ~
7210 7210 \SpecialChar ~
7211 7211 \SpecialChar ~
7212 7212 \SpecialChar ~
7213 7213 \SpecialChar ~
7214 7214 \SpecialChar ~
7215 7215 \SpecialChar ~
7216 7216 \SpecialChar ~
7217 7217 \SpecialChar ~
7218 7218 <8> 'scopes.py
7219 7219 \backslash
7220 7220 nstrings.py'
7221 7221 \layout Standard
7222 7222
7223 7223
7224 7224 \family typewriter
7225 7225 fperez[~/test]|9> $$alist = ls *s.py
7226 7226 \newline
7227 7227 fperez[~/test]|10> alist
7228 7228 \newline
7229 7229
7230 7230 \begin_inset ERT
7231 7231 status Collapsed
7232 7232
7233 7233 \layout Standard
7234 7234
7235 7235 \backslash
7236 7236 hspace*{0mm}
7237 7237 \end_inset
7238 7238
7239 7239 \SpecialChar ~
7240 7240 \SpecialChar ~
7241 7241 \SpecialChar ~
7242 7242 \SpecialChar ~
7243 7243 \SpecialChar ~
7244 7244 \SpecialChar ~
7245 7245 \SpecialChar ~
7246 7246 \SpecialChar ~
7247 7247 \SpecialChar ~
7248 7248 \SpecialChar ~
7249 7249 \SpecialChar ~
7250 7250 \SpecialChar ~
7251 7251 \SpecialChar ~
7252 7252 \SpecialChar ~
7253 7253 <10> ['scopes.py', 'strings.py']
7254 7254 \layout Standard
7255 7255
7256 7256 alist is now a normal python list you can loop over.
7257 7257 Using
7258 7258 \family typewriter
7259 7259 $
7260 7260 \family default
7261 7261 will expand back the python values when alias calls are made:
7262 7262 \layout Standard
7263 7263
7264 7264
7265 7265 \family typewriter
7266 7266 fperez[~/test]|11> for f in alist:
7267 7267 \newline
7268 7268
7269 7269 \begin_inset ERT
7270 7270 status Collapsed
7271 7271
7272 7272 \layout Standard
7273 7273
7274 7274 \backslash
7275 7275 hspace*{0mm}
7276 7276 \end_inset
7277 7277
7278 7278 \SpecialChar ~
7279 7279 \SpecialChar ~
7280 7280 \SpecialChar ~
7281 7281 \SpecialChar ~
7282 7282 \SpecialChar ~
7283 7283 \SpecialChar ~
7284 7284 \SpecialChar ~
7285 7285 \SpecialChar ~
7286 7286 \SpecialChar ~
7287 7287 \SpecialChar ~
7288 7288 \SpecialChar ~
7289 7289 \SpecialChar ~
7290 7290 \SpecialChar ~
7291 7291 \SpecialChar ~
7292 7292 |..> \SpecialChar ~
7293 7293 \SpecialChar ~
7294 7294 \SpecialChar ~
7295 7295 \SpecialChar ~
7296 7296 print 'file',f,
7297 7297 \newline
7298 7298
7299 7299 \begin_inset ERT
7300 7300 status Collapsed
7301 7301
7302 7302 \layout Standard
7303 7303
7304 7304 \backslash
7305 7305 hspace*{0mm}
7306 7306 \end_inset
7307 7307
7308 7308 \SpecialChar ~
7309 7309 \SpecialChar ~
7310 7310 \SpecialChar ~
7311 7311 \SpecialChar ~
7312 7312 \SpecialChar ~
7313 7313 \SpecialChar ~
7314 7314 \SpecialChar ~
7315 7315 \SpecialChar ~
7316 7316 \SpecialChar ~
7317 7317 \SpecialChar ~
7318 7318 \SpecialChar ~
7319 7319 \SpecialChar ~
7320 7320 \SpecialChar ~
7321 7321 \SpecialChar ~
7322 7322 |..> \SpecialChar ~
7323 7323 \SpecialChar ~
7324 7324 \SpecialChar ~
7325 7325 \SpecialChar ~
7326 7326 wc -l $f
7327 7327 \newline
7328 7328
7329 7329 \begin_inset ERT
7330 7330 status Collapsed
7331 7331
7332 7332 \layout Standard
7333 7333
7334 7334 \backslash
7335 7335 hspace*{0mm}
7336 7336 \end_inset
7337 7337
7338 7338 \SpecialChar ~
7339 7339 \SpecialChar ~
7340 7340 \SpecialChar ~
7341 7341 \SpecialChar ~
7342 7342 \SpecialChar ~
7343 7343 \SpecialChar ~
7344 7344 \SpecialChar ~
7345 7345 \SpecialChar ~
7346 7346 \SpecialChar ~
7347 7347 \SpecialChar ~
7348 7348 \SpecialChar ~
7349 7349 \SpecialChar ~
7350 7350 \SpecialChar ~
7351 7351 \SpecialChar ~
7352 7352 |..>
7353 7353 \newline
7354 7354 file scopes.py 13 scopes.py
7355 7355 \newline
7356 7356 file strings.py 4 strings.py
7357 7357 \layout Standard
7358 7358
7359 7359 Note that you may need to protect your variables with braces if you want
7360 7360 to append strings to their names.
7361 7361 To copy all files in alist to
7362 7362 \family typewriter
7363 7363 .bak
7364 7364 \family default
7365 7365 extensions, you must use:
7366 7366 \layout Standard
7367 7367
7368 7368
7369 7369 \family typewriter
7370 7370 fperez[~/test]|12> for f in alist:
7371 7371 \newline
7372 7372
7373 7373 \begin_inset ERT
7374 7374 status Collapsed
7375 7375
7376 7376 \layout Standard
7377 7377
7378 7378 \backslash
7379 7379 hspace*{0mm}
7380 7380 \end_inset
7381 7381
7382 7382 \SpecialChar ~
7383 7383 \SpecialChar ~
7384 7384 \SpecialChar ~
7385 7385 \SpecialChar ~
7386 7386 \SpecialChar ~
7387 7387 \SpecialChar ~
7388 7388 \SpecialChar ~
7389 7389 \SpecialChar ~
7390 7390 \SpecialChar ~
7391 7391 \SpecialChar ~
7392 7392 \SpecialChar ~
7393 7393 \SpecialChar ~
7394 7394 \SpecialChar ~
7395 7395 \SpecialChar ~
7396 7396 |..> \SpecialChar ~
7397 7397 \SpecialChar ~
7398 7398 \SpecialChar ~
7399 7399 \SpecialChar ~
7400 7400 cp $f ${f}.bak
7401 7401 \layout Standard
7402 7402
7403 7403 If you try using
7404 7404 \family typewriter
7405 7405 $f.bak
7406 7406 \family default
7407 7407 , you'll get an AttributeError exception saying that your string object
7408 7408 doesn't have a
7409 7409 \family typewriter
7410 7410 .bak
7411 7411 \family default
7412 7412 attribute.
7413 7413 This is because the
7414 7414 \family typewriter
7415 7415 $
7416 7416 \family default
7417 7417 expansion mechanism allows you to expand full Python expressions:
7418 7418 \layout Standard
7419 7419
7420 7420
7421 7421 \family typewriter
7422 7422 fperez[~/test]|13> echo "sys.platform is: $sys.platform"
7423 7423 \newline
7424 7424 sys.platform is: linux2
7425 7425 \layout Standard
7426 7426
7427 7427 IPython's input history handling is still active, which allows you to rerun
7428 7428 a single block of multi-line input by simply using exec:
7429 7429 \newline
7430 7430
7431 7431 \family typewriter
7432 7432 fperez[~/test]|14> $$alist = ls *.eps
7433 7433 \newline
7434 7434 fperez[~/test]|15> exec _i11
7435 7435 \newline
7436 7436 file image2.eps 921 image2.eps
7437 7437 \newline
7438 7438 file image.eps 921 image.eps
7439 7439 \layout Standard
7440 7440
7441 7441 While these are new special-case syntaxes, they are designed to allow very
7442 7442 efficient use of the shell with minimal typing.
7443 7443 At an interactive shell prompt, conciseness of expression wins over readability.
7444 7444 \layout Subsection
7445 7445
7446 7446 Useful functions and modules
7447 7447 \layout Standard
7448 7448
7449 7449 The os, sys and shutil modules from the Python standard library are automaticall
7450 7450 y loaded.
7451 7451 Some additional functions, useful for shell usage, are listed below.
7452 7452 You can request more help about them with `
7453 7453 \family typewriter
7454 7454 ?
7455 7455 \family default
7456 7456 '.
7457 7457 \layout Description
7458 7458
7459 7459
7460 7460 \family typewriter
7461 7461 shell
7462 7462 \family default
7463 7463 - execute a command in the underlying system shell
7464 7464 \layout Description
7465 7465
7466 7466
7467 7467 \family typewriter
7468 7468 system
7469 7469 \family default
7470 7470 - like
7471 7471 \family typewriter
7472 7472 shell()
7473 7473 \family default
7474 7474 , but return the exit status of the command
7475 7475 \layout Description
7476 7476
7477 7477
7478 7478 \family typewriter
7479 7479 sout
7480 7480 \family default
7481 7481 - capture the output of a command as a string
7482 7482 \layout Description
7483 7483
7484 7484
7485 7485 \family typewriter
7486 7486 lout
7487 7487 \family default
7488 7488 - capture the output of a command as a list (split on `
7489 7489 \backslash
7490 7490 n')
7491 7491 \layout Description
7492 7492
7493 7493
7494 7494 \family typewriter
7495 7495 getoutputerror
7496 7496 \family default
7497 7497 - capture (output,error) of a shell commandss
7498 7498 \layout Standard
7499 7499
7500 7500
7501 7501 \family typewriter
7502 7502 sout
7503 7503 \family default
7504 7504 /
7505 7505 \family typewriter
7506 7506 lout
7507 7507 \family default
7508 7508 are the functional equivalents of
7509 7509 \family typewriter
7510 7510 $
7511 7511 \family default
7512 7512 /
7513 7513 \family typewriter
7514 7514 $$
7515 7515 \family default
7516 7516 .
7517 7517 They are provided to allow you to capture system output in the middle of
7518 7518 true python code, function definitions, etc (where
7519 7519 \family typewriter
7520 7520 $
7521 7521 \family default
7522 7522 and
7523 7523 \family typewriter
7524 7524 $$
7525 7525 \family default
7526 7526 are invalid).
7527 7527 \layout Subsection
7528 7528
7529 7529 Directory management
7530 7530 \layout Standard
7531 7531
7532 7532 Since each command passed by pysh to the underlying system is executed in
7533 7533 a subshell which exits immediately, you can NOT use !cd to navigate the
7534 7534 filesystem.
7535 7535 \layout Standard
7536 7536
7537 7537 Pysh provides its own builtin
7538 7538 \family typewriter
7539 7539 `%cd
7540 7540 \family default
7541 7541 ' magic command to move in the filesystem (the
7542 7542 \family typewriter
7543 7543 %
7544 7544 \family default
7545 7545 is not required with automagic on).
7546 7546 It also maintains a list of visited directories (use
7547 7547 \family typewriter
7548 7548 %dhist
7549 7549 \family default
7550 7550 to see it) and allows direct switching to any of them.
7551 7551 Type
7552 7552 \family typewriter
7553 7553 `cd?
7554 7554 \family default
7555 7555 ' for more details.
7556 7556 \layout Standard
7557 7557
7558 7558
7559 7559 \family typewriter
7560 7560 %pushd
7561 7561 \family default
7562 7562 ,
7563 7563 \family typewriter
7564 7564 %popd
7565 7565 \family default
7566 7566 and
7567 7567 \family typewriter
7568 7568 %dirs
7569 7569 \family default
7570 7570 are provided for directory stack handling.
7571 7571 \layout Subsection
7572 7572
7573 7573 Prompt customization
7574 7574 \layout Standard
7575 7575
7576 7576 The supplied
7577 7577 \family typewriter
7578 7578 ipythonrc-pysh
7579 7579 \family default
7580 7580 profile comes with an example of a very colored and detailed prompt, mainly
7581 7581 to serve as an illustration.
7582 7582 The valid escape sequences, besides color names, are:
7583 7583 \layout Description
7584 7584
7585 7585
7586 7586 \backslash
7587 7587 # - Prompt number.
7588 7588 \layout Description
7589 7589
7590 7590
7591 7591 \backslash
7592 7592 D - Dots, as many as there are digits in
7593 7593 \backslash
7594 7594 # (so they align).
7595 7595 \layout Description
7596 7596
7597 7597
7598 7598 \backslash
7599 7599 w - Current working directory (cwd).
7600 7600 \layout Description
7601 7601
7602 7602
7603 7603 \backslash
7604 7604 W - Basename of current working directory.
7605 7605 \layout Description
7606 7606
7607 7607
7608 7608 \backslash
7609 7609 X
7610 7610 \emph on
7611 7611 N
7612 7612 \emph default
7613 7613 - Where
7614 7614 \emph on
7615 7615 N
7616 7616 \emph default
7617 7617 =0..5.
7618 7618 N terms of the cwd, with $HOME written as ~.
7619 7619 \layout Description
7620 7620
7621 7621
7622 7622 \backslash
7623 7623 Y
7624 7624 \emph on
7625 7625 N
7626 7626 \emph default
7627 7627 - Where
7628 7628 \emph on
7629 7629 N
7630 7630 \emph default
7631 7631 =0..5.
7632 7632 Like X
7633 7633 \emph on
7634 7634 N
7635 7635 \emph default
7636 7636 , but if ~ is term
7637 7637 \emph on
7638 7638 N
7639 7639 \emph default
7640 7640 +1 it's also shown.
7641 7641 \layout Description
7642 7642
7643 7643
7644 7644 \backslash
7645 7645 u - Username.
7646 7646 \layout Description
7647 7647
7648 7648
7649 7649 \backslash
7650 7650 H - Full hostname.
7651 7651 \layout Description
7652 7652
7653 7653
7654 7654 \backslash
7655 7655 h - Hostname up to first '.'
7656 7656 \layout Description
7657 7657
7658 7658
7659 7659 \backslash
7660 7660 $ - Root symbol ($ or #).
7661 7661
7662 7662 \layout Description
7663 7663
7664 7664
7665 7665 \backslash
7666 7666 t - Current time, in H:M:S format.
7667 7667 \layout Description
7668 7668
7669 7669
7670 7670 \backslash
7671 7671 v - IPython release version.
7672 7672
7673 7673 \layout Description
7674 7674
7675 7675
7676 7676 \backslash
7677 7677 n - Newline.
7678 7678
7679 7679 \layout Description
7680 7680
7681 7681
7682 7682 \backslash
7683 7683 r - Carriage return.
7684 7684
7685 7685 \layout Description
7686 7686
7687 7687
7688 7688 \backslash
7689 7689
7690 7690 \backslash
7691 7691 - An explicitly escaped '
7692 7692 \backslash
7693 7693 '.
7694 7694 \layout Standard
7695 7695
7696 7696 You can configure your prompt colors using any ANSI color escape.
7697 7697 Each color escape sets the color for any subsequent text, until another
7698 7698 escape comes in and changes things.
7699 7699 The valid color escapes are:
7700 7700 \layout Description
7701 7701
7702 7702
7703 7703 \backslash
7704 7704 C_Black
7705 7705 \layout Description
7706 7706
7707 7707
7708 7708 \backslash
7709 7709 C_Blue
7710 7710 \layout Description
7711 7711
7712 7712
7713 7713 \backslash
7714 7714 C_Brown
7715 7715 \layout Description
7716 7716
7717 7717
7718 7718 \backslash
7719 7719 C_Cyan
7720 7720 \layout Description
7721 7721
7722 7722
7723 7723 \backslash
7724 7724 C_DarkGray
7725 7725 \layout Description
7726 7726
7727 7727
7728 7728 \backslash
7729 7729 C_Green
7730 7730 \layout Description
7731 7731
7732 7732
7733 7733 \backslash
7734 7734 C_LightBlue
7735 7735 \layout Description
7736 7736
7737 7737
7738 7738 \backslash
7739 7739 C_LightCyan
7740 7740 \layout Description
7741 7741
7742 7742
7743 7743 \backslash
7744 7744 C_LightGray
7745 7745 \layout Description
7746 7746
7747 7747
7748 7748 \backslash
7749 7749 C_LightGreen
7750 7750 \layout Description
7751 7751
7752 7752
7753 7753 \backslash
7754 7754 C_LightPurple
7755 7755 \layout Description
7756 7756
7757 7757
7758 7758 \backslash
7759 7759 C_LightRed
7760 7760 \layout Description
7761 7761
7762 7762
7763 7763 \backslash
7764 7764 C_Purple
7765 7765 \layout Description
7766 7766
7767 7767
7768 7768 \backslash
7769 7769 C_Red
7770 7770 \layout Description
7771 7771
7772 7772
7773 7773 \backslash
7774 7774 C_White
7775 7775 \layout Description
7776 7776
7777 7777
7778 7778 \backslash
7779 7779 C_Yellow
7780 7780 \layout Description
7781 7781
7782 7782
7783 7783 \backslash
7784 7784 C_Normal Stop coloring, defaults to your terminal settings.
7785 7785 \layout Section
7786 7786
7787 7787
7788 7788 \begin_inset LatexCommand \label{sec:Threading-support}
7789 7789
7790 7790 \end_inset
7791 7791
7792 7792 Threading support
7793 7793 \layout Standard
7794 7794
7795 7795
7796 7796 \series bold
7797 7797 WARNING:
7798 7798 \series default
7799 7799 The threading support is still somewhat experimental, and it has only seen
7800 7800 reasonable testing under Linux.
7801 7801 Threaded code is particularly tricky to debug, and it tends to show extremely
7802 7802 platform-dependent behavior.
7803 7803 Since I only have access to Linux machines, I will have to rely on user's
7804 7804 experiences and assistance for this area of IPython to improve under other
7805 7805 platforms.
7806 7806 \layout Standard
7807 7807
7808 7808 IPython, via the
7809 7809 \family typewriter
7810 7810 -gthread
7811 7811 \family default
7812 7812 ,
7813 7813 \family typewriter
7814 7814 -qthread
7815 7815 \family default
7816 7816 and
7817 7817 \family typewriter
7818 7818 -wthread
7819 7819 \family default
7820 7820 options (described in Sec.\SpecialChar ~
7821 7821
7822 7822 \begin_inset LatexCommand \ref{sec:threading-opts}
7823 7823
7824 7824 \end_inset
7825 7825
7826 7826 ), can run in multithreaded mode to support pyGTK, Qt and WXPython applications
7827 7827 respectively.
7828 7828 These GUI toolkits need to control the python main loop of execution, so
7829 7829 under a normal Python interpreter, starting a pyGTK, Qt or WXPython application
7830 7830 will immediately freeze the shell.
7831 7831
7832 7832 \layout Standard
7833 7833
7834 7834 IPython, with one of these options (you can only use one at a time), separates
7835 7835 the graphical loop and IPython's code execution run into different threads.
7836 7836 This allows you to test interactively (with
7837 7837 \family typewriter
7838 7838 %run
7839 7839 \family default
7840 7840 , for example) your GUI code without blocking.
7841 7841 \layout Standard
7842 7842
7843 7843 A nice mini-tutorial on using IPython along with the Qt Designer application
7844 7844 is available at the SciPy wiki:
7845 7845 \begin_inset LatexCommand \htmlurl{http://www.scipy.org/wikis/topical_software/QtWithIPythonAndDesigner}
7846 7846
7847 7847 \end_inset
7848 7848
7849 7849 .
7850 7850 \layout Subsection
7851 7851
7852 7852 Tk issues
7853 7853 \layout Standard
7854 7854
7855 7855 As indicated in Sec.\SpecialChar ~
7856 7856
7857 7857 \begin_inset LatexCommand \ref{sec:threading-opts}
7858 7858
7859 7859 \end_inset
7860 7860
7861 7861 , a special
7862 7862 \family typewriter
7863 7863 -tk
7864 7864 \family default
7865 7865 option is provided to try and allow Tk graphical applications to coexist
7866 7866 interactively with WX, Qt or GTK ones.
7867 7867 Whether this works at all, however, is very platform and configuration
7868 7868 dependent.
7869 7869 Please experiment with simple test cases before committing to using this
7870 7870 combination of Tk and GTK/Qt/WX threading in a production environment.
7871 7871 \layout Subsection
7872 7872
7873 7873 Signals and Threads
7874 7874 \layout Standard
7875 7875
7876 7876 When any of the thread systems (GTK, Qt or WX) are active, either directly
7877 7877 or via
7878 7878 \family typewriter
7879 7879 -pylab
7880 7880 \family default
7881 7881 with a threaded backend, it is impossible to interrupt long-running Python
7882 7882 code via
7883 7883 \family typewriter
7884 7884 Ctrl-C
7885 7885 \family default
7886 7886 .
7887 7887 IPython can not pass the KeyboardInterrupt exception (or the underlying
7888 7888
7889 7889 \family typewriter
7890 7890 SIGINT
7891 7891 \family default
7892 7892 ) across threads, so any long-running process started from IPython will
7893 7893 run to completion, or will have to be killed via an external (OS-based)
7894 7894 mechanism.
7895 7895 \layout Standard
7896 7896
7897 7897 To the best of my knowledge, this limitation is imposed by the Python interprete
7898 7898 r itself, and it comes from the difficulty of writing portable signal/threaded
7899 7899 code.
7900 7900 If any user is an expert on this topic and can suggest a better solution,
7901 7901 I would love to hear about it.
7902 7902 In the IPython sources, look at the
7903 7903 \family typewriter
7904 7904 Shell.py
7905 7905 \family default
7906 7906 module, and in particular at the
7907 7907 \family typewriter
7908 7908 runcode()
7909 7909 \family default
7910 7910 method.
7911 7911
7912 7912 \layout Subsection
7913 7913
7914 7914 I/O pitfalls
7915 7915 \layout Standard
7916 7916
7917 7917 Be mindful that the Python interpreter switches between threads every
7918 7918 \begin_inset Formula $N$
7919 7919 \end_inset
7920 7920
7921 7921 bytecodes, where the default value as of Python\SpecialChar ~
7922 7922 2.3 is
7923 7923 \begin_inset Formula $N=100.$
7924 7924 \end_inset
7925 7925
7926 7926 This value can be read by using the
7927 7927 \family typewriter
7928 7928 sys.getcheckinterval()
7929 7929 \family default
7930 7930 function, and it can be reset via
7931 7931 \family typewriter
7932 7932 sys.setcheckinterval(
7933 7933 \emph on
7934 7934 N
7935 7935 \emph default
7936 7936 )
7937 7937 \family default
7938 7938 .
7939 7939 This switching of threads can cause subtly confusing effects if one of
7940 7940 your threads is doing file I/O.
7941 7941 In text mode, most systems only flush file buffers when they encounter
7942 7942 a
7943 7943 \family typewriter
7944 7944 `
7945 7945 \backslash
7946 7946 n'
7947 7947 \family default
7948 7948 .
7949 7949 An instruction as simple as
7950 7950 \family typewriter
7951 7951
7952 7952 \newline
7953 7953 \SpecialChar ~
7954 7954 \SpecialChar ~
7955 7955 print >> filehandle,
7956 7956 \begin_inset Quotes eld
7957 7957 \end_inset
7958 7958
7959 7959 hello world
7960 7960 \begin_inset Quotes erd
7961 7961 \end_inset
7962 7962
7963 7963
7964 7964 \family default
7965 7965
7966 7966 \newline
7967 7967 actually consists of several bytecodes, so it is possible that the newline
7968 7968 does not reach your file before the next thread switch.
7969 7969 Similarly, if you are writing to a file in binary mode, the file won't
7970 7970 be flushed until the buffer fills, and your other thread may see apparently
7971 7971 truncated files.
7972 7972
7973 7973 \layout Standard
7974 7974
7975 7975 For this reason, if you are using IPython's thread support and have (for
7976 7976 example) a GUI application which will read data generated by files written
7977 7977 to from the IPython thread, the safest approach is to open all of your
7978 7978 files in unbuffered mode (the third argument to the
7979 7979 \family typewriter
7980 7980 file/open
7981 7981 \family default
7982 7982 function is the buffering value):
7983 7983 \newline
7984 7984
7985 7985 \family typewriter
7986 7986 \SpecialChar ~
7987 7987 \SpecialChar ~
7988 7988 filehandle = open(filename,mode,0)
7989 7989 \layout Standard
7990 7990
7991 7991 This is obviously a brute force way of avoiding race conditions with the
7992 7992 file buffering.
7993 7993 If you want to do it cleanly, and you have a resource which is being shared
7994 7994 by the interactive IPython loop and your GUI thread, you should really
7995 7995 handle it with thread locking and syncrhonization properties.
7996 7996 The Python documentation discusses these.
7997 7997 \layout Section
7998 7998
7999 7999
8000 8000 \begin_inset LatexCommand \label{sec:interactive-demos}
8001 8001
8002 8002 \end_inset
8003 8003
8004 8004 Interactive demos with IPython
8005 8005 \layout Standard
8006 8006
8007 8007 IPython ships with a basic system for running scripts interactively in sections,
8008 8008 useful when presenting code to audiences.
8009 8009 A few tags embedded in comments (so that the script remains valid Python
8010 8010 code) divide a file into separate blocks, and the demo can be run one block
8011 8011 at a time, with IPython printing (with syntax highlighting) the block before
8012 8012 executing it, and returning to the interactive prompt after each block.
8013 8013 The interactive namespace is updated after each block is run with the contents
8014 8014 of the demo's namespace.
8015 8015 \layout Standard
8016 8016
8017 8017 This allows you to show a piece of code, run it and then execute interactively
8018 8018 commands based on the variables just created.
8019 8019 Once you want to continue, you simply execute the next block of the demo.
8020 8020 The following listing shows the markup necessary for dividing a script
8021 8021 into sections for execution as a demo.
8022 8022 \layout Standard
8023 8023
8024 8024
8025 8025 \begin_inset ERT
8026 8026 status Open
8027 8027
8028 8028 \layout Standard
8029 8029
8030 8030 \backslash
8031 8031 codelist{examples/example-demo.py}
8032 8032 \end_inset
8033 8033
8034 8034
8035 8035 \layout Standard
8036 8036
8037 8037 In order to run a file as a demo, you must first make a
8038 8038 \family typewriter
8039 8039 Demo
8040 8040 \family default
8041 8041 object out of it.
8042 8042 If the file is named
8043 8043 \family typewriter
8044 8044 myscript.py
8045 8045 \family default
8046 8046 , the following code will make a demo:
8047 8047 \layout LyX-Code
8048 8048
8049 8049 from IPython.demo import Demo
8050 8050 \layout LyX-Code
8051 8051
8052 8052 mydemo = Demo('myscript.py')
8053 8053 \layout Standard
8054 8054
8055 8055 This creates the
8056 8056 \family typewriter
8057 8057 mydemo
8058 8058 \family default
8059 8059 object, whose blocks you run one at a time by simply calling the object
8060 8060 with no arguments.
8061 8061 If you have autocall active in IPython (the default), all you need to do
8062 8062 is type
8063 8063 \layout LyX-Code
8064 8064
8065 8065 mydemo
8066 8066 \layout Standard
8067 8067
8068 8068 and IPython will call it, executing each block.
8069 8069 Demo objects can be restarted, you can move forward or back skipping blocks,
8070 8070 re-execute the last block, etc.
8071 8071 Simply use the Tab key on a demo object to see its methods, and call
8072 8072 \family typewriter
8073 8073 `?'
8074 8074 \family default
8075 8075 on them to see their docstrings for more usage details.
8076 8076 In addition, the
8077 8077 \family typewriter
8078 8078 demo
8079 8079 \family default
8080 8080 module itself contains a comprehensive docstring, which you can access
8081 8081 via
8082 8082 \layout LyX-Code
8083 8083
8084 8084 from IPython import demo
8085 8085 \layout LyX-Code
8086 8086
8087 8087 demo?
8088 8088 \layout Standard
8089 8089
8090 8090
8091 8091 \series bold
8092 8092 Limitations:
8093 8093 \series default
8094 8094 It is important to note that these demos are limited to fairly simple uses.
8095 8095 In particular, you can
8096 8096 \emph on
8097 8097 not
8098 8098 \emph default
8099 8099 put division marks in indented code (loops, if statements, function definitions
8100 8100 , etc.) Supporting something like this would basically require tracking the
8101 8101 internal execution state of the Python interpreter, so only top-level divisions
8102 8102 are allowed.
8103 8103 If you want to be able to open an IPython instance at an arbitrary point
8104 8104 in a program, you can use IPython's embedding facilities, described in
8105 8105 detail in Sec\SpecialChar \@.
8106 8106 \SpecialChar ~
8107 8107
8108 8108 \begin_inset LatexCommand \ref{sec:embed}
8109 8109
8110 8110 \end_inset
8111 8111
8112 8112 .
8113 8113 \layout Section
8114 8114
8115 8115
8116 8116 \begin_inset LatexCommand \label{sec:matplotlib-support}
8117 8117
8118 8118 \end_inset
8119 8119
8120 8120 Plotting with
8121 8121 \family typewriter
8122 8122 matplotlib
8123 8123 \family default
8124 8124
8125 8125 \layout Standard
8126 8126
8127 8127 The matplotlib library (
8128 8128 \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}
8129 8129
8130 8130 \end_inset
8131 8131
8132 8132 ) provides high quality 2D plotting for Python.
8133 8133 Matplotlib can produce plots on screen using a variety of GUI toolkits,
8134 8134 including Tk, GTK and WXPython.
8135 8135 It also provides a number of commands useful for scientific computing,
8136 8136 all with a syntax compatible with that of the popular Matlab program.
8137 8137 \layout Standard
8138 8138
8139 8139 IPython accepts the special option
8140 8140 \family typewriter
8141 8141 -pylab
8142 8142 \family default
8143 8143 (Sec.\SpecialChar ~
8144 8144
8145 8145 \begin_inset LatexCommand \ref{sec:cmd-line-opts}
8146 8146
8147 8147 \end_inset
8148 8148
8149 8149 ).
8150 8150 This configures it to support matplotlib, honoring the settings in the
8151 8151
8152 8152 \family typewriter
8153 8153 .matplotlibrc
8154 8154 \family default
8155 8155 file.
8156 8156 IPython will detect the user's choice of matplotlib GUI backend, and automatica
8157 8157 lly select the proper threading model to prevent blocking.
8158 8158 It also sets matplotlib in interactive mode and modifies
8159 8159 \family typewriter
8160 8160 %run
8161 8161 \family default
8162 8162 slightly, so that any matplotlib-based script can be executed using
8163 8163 \family typewriter
8164 8164 %run
8165 8165 \family default
8166 8166 and the final
8167 8167 \family typewriter
8168 8168 show()
8169 8169 \family default
8170 8170 command does not block the interactive shell.
8171 8171 \layout Standard
8172 8172
8173 8173 The
8174 8174 \family typewriter
8175 8175 -pylab
8176 8176 \family default
8177 8177 option must be given first in order for IPython to configure its threading
8178 8178 mode.
8179 8179 However, you can still issue other options afterwards.
8180 8180 This allows you to have a matplotlib-based environment customized with
8181 8181 additional modules using the standard IPython profile mechanism (Sec.\SpecialChar ~
8182 8182
8183 8183 \begin_inset LatexCommand \ref{sec:profiles}
8184 8184
8185 8185 \end_inset
8186 8186
8187 8187 ): ``
8188 8188 \family typewriter
8189 8189 ipython -pylab -p myprofile
8190 8190 \family default
8191 8191 '' will load the profile defined in
8192 8192 \family typewriter
8193 8193 ipythonrc-myprofile
8194 8194 \family default
8195 8195 after configuring matplotlib.
8196 8196 \layout Section
8197 8197
8198 8198
8199 8199 \begin_inset LatexCommand \label{sec:Gnuplot}
8200 8200
8201 8201 \end_inset
8202 8202
8203 8203 Plotting with
8204 8204 \family typewriter
8205 8205 Gnuplot
8206 8206 \layout Standard
8207 8207
8208 8208 Through the magic extension system described in sec.
8209 8209
8210 8210 \begin_inset LatexCommand \ref{sec:magic}
8211 8211
8212 8212 \end_inset
8213 8213
8214 8214 , IPython incorporates a mechanism for conveniently interfacing with the
8215 8215 Gnuplot system (
8216 8216 \begin_inset LatexCommand \htmlurl{http://www.gnuplot.info}
8217 8217
8218 8218 \end_inset
8219 8219
8220 8220 ).
8221 8221 Gnuplot is a very complete 2D and 3D plotting package available for many
8222 8222 operating systems and commonly included in modern Linux distributions.
8223 8223
8224 8224 \layout Standard
8225 8225
8226 8226 Besides having Gnuplot installed, this functionality requires the
8227 8227 \family typewriter
8228 8228 Gnuplot.py
8229 8229 \family default
8230 8230 module for interfacing python with Gnuplot.
8231 8231 It can be downloaded from:
8232 8232 \begin_inset LatexCommand \htmlurl{http://gnuplot-py.sourceforge.net}
8233 8233
8234 8234 \end_inset
8235 8235
8236 8236 .
8237 8237 \layout Subsection
8238 8238
8239 8239 Proper Gnuplot configuration
8240 8240 \layout Standard
8241 8241
8242 8242 As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support.
8243 8243 However, as of
8244 8244 \family typewriter
8245 8245 Gnuplot.py
8246 8246 \family default
8247 8247 version 1.7, a new option was added to communicate between Python and Gnuplot
8248 8248 via FIFOs (pipes).
8249 8249 This mechanism, while fast, also breaks the mouse system.
8250 8250 You must therefore set the variable
8251 8251 \family typewriter
8252 8252 prefer_fifo_data
8253 8253 \family default
8254 8254 to
8255 8255 \family typewriter
8256 8256 0
8257 8257 \family default
8258 8258 in file
8259 8259 \family typewriter
8260 8260 gp_unix.py
8261 8261 \family default
8262 8262 if you wish to keep the interactive mouse and keyboard features working
8263 8263 properly (
8264 8264 \family typewriter
8265 8265 prefer_inline_data
8266 8266 \family default
8267 8267 also must be
8268 8268 \family typewriter
8269 8269 0
8270 8270 \family default
8271 8271 , but this is the default so unless you've changed it manually you should
8272 8272 be fine).
8273 8273 \layout Standard
8274 8274
8275 8275 'Out of the box', Gnuplot is configured with a rather poor set of size,
8276 8276 color and linewidth choices which make the graphs fairly hard to read on
8277 8277 modern high-resolution displays (although they work fine on old 640x480
8278 8278 ones).
8279 8279 Below is a section of my
8280 8280 \family typewriter
8281 8281 .Xdefaults
8282 8282 \family default
8283 8283 file which I use for having a more convenient Gnuplot setup.
8284 8284 Remember to load it by running
8285 8285 \family typewriter
8286 8286 `xrdb .Xdefaults`
8287 8287 \family default
8288 8288 :
8289 8289 \layout Standard
8290 8290
8291 8291
8292 8292 \family typewriter
8293 8293 !******************************************************************
8294 8294 \newline
8295 8295 ! gnuplot options
8296 8296 \newline
8297 8297 ! modify this for a convenient window size
8298 8298 \newline
8299 8299 gnuplot*geometry: 780x580
8300 8300 \layout Standard
8301 8301
8302 8302
8303 8303 \family typewriter
8304 8304 ! on-screen font (not for PostScript)
8305 8305 \newline
8306 8306 gnuplot*font: -misc-fixed-bold-r-normal--15-120-100-100-c-90-iso8859-1
8307 8307 \layout Standard
8308 8308
8309 8309
8310 8310 \family typewriter
8311 8311 ! color options
8312 8312 \newline
8313 8313 gnuplot*background: black
8314 8314 \newline
8315 8315 gnuplot*textColor: white
8316 8316 \newline
8317 8317 gnuplot*borderColor: white
8318 8318 \newline
8319 8319 gnuplot*axisColor: white
8320 8320 \newline
8321 8321 gnuplot*line1Color: red
8322 8322 \newline
8323 8323 gnuplot*line2Color: green
8324 8324 \newline
8325 8325 gnuplot*line3Color: blue
8326 8326 \newline
8327 8327 gnuplot*line4Color: magenta
8328 8328 \newline
8329 8329 gnuplot*line5Color: cyan
8330 8330 \newline
8331 8331 gnuplot*line6Color: sienna
8332 8332 \newline
8333 8333 gnuplot*line7Color: orange
8334 8334 \newline
8335 8335 gnuplot*line8Color: coral
8336 8336 \layout Standard
8337 8337
8338 8338
8339 8339 \family typewriter
8340 8340 ! multiplicative factor for point styles
8341 8341 \newline
8342 8342 gnuplot*pointsize: 2
8343 8343 \layout Standard
8344 8344
8345 8345
8346 8346 \family typewriter
8347 8347 ! line width options (in pixels)
8348 8348 \newline
8349 8349 gnuplot*borderWidth: 2
8350 8350 \newline
8351 8351 gnuplot*axisWidth: 2
8352 8352 \newline
8353 8353 gnuplot*line1Width: 2
8354 8354 \newline
8355 8355 gnuplot*line2Width: 2
8356 8356 \newline
8357 8357 gnuplot*line3Width: 2
8358 8358 \newline
8359 8359 gnuplot*line4Width: 2
8360 8360 \newline
8361 8361 gnuplot*line5Width: 2
8362 8362 \newline
8363 8363 gnuplot*line6Width: 2
8364 8364 \newline
8365 8365 gnuplot*line7Width: 2
8366 8366 \newline
8367 8367 gnuplot*line8Width: 2
8368 8368 \layout Subsection
8369 8369
8370 8370 The
8371 8371 \family typewriter
8372 8372 IPython.GnuplotRuntime
8373 8373 \family default
8374 8374 module
8375 8375 \layout Standard
8376 8376
8377 8377 IPython includes a module called
8378 8378 \family typewriter
8379 8379 Gnuplot2.py
8380 8380 \family default
8381 8381 which extends and improves the default
8382 8382 \family typewriter
8383 8383 Gnuplot
8384 8384 \family default
8385 8385 .
8386 8386 \family typewriter
8387 8387 py
8388 8388 \family default
8389 8389 (which it still relies upon).
8390 8390 For example, the new
8391 8391 \family typewriter
8392 8392 plot
8393 8393 \family default
8394 8394 function adds several improvements to the original making it more convenient
8395 8395 for interactive use, and
8396 8396 \family typewriter
8397 8397 hardcopy
8398 8398 \family default
8399 8399 fixes a bug in the original which under some circumstances blocks the creation
8400 8400 of PostScript output.
8401 8401 \layout Standard
8402 8402
8403 8403 For scripting use,
8404 8404 \family typewriter
8405 8405 GnuplotRuntime.py
8406 8406 \family default
8407 8407 is provided, which wraps
8408 8408 \family typewriter
8409 8409 Gnuplot2.py
8410 8410 \family default
8411 8411 and creates a series of global aliases.
8412 8412 These make it easy to control Gnuplot plotting jobs through the Python
8413 8413 language.
8414 8414 \layout Standard
8415 8415
8416 8416 Below is some example code which illustrates how to configure Gnuplot inside
8417 8417 your own programs but have it available for further interactive use through
8418 8418 an embedded IPython instance.
8419 8419 Simply run this file at a system prompt.
8420 8420 This file is provided as
8421 8421 \family typewriter
8422 8422 example-gnuplot.py
8423 8423 \family default
8424 8424 in the examples directory:
8425 8425 \layout Standard
8426 8426
8427 8427
8428 8428 \begin_inset ERT
8429 8429 status Open
8430 8430
8431 8431 \layout Standard
8432 8432
8433 8433 \backslash
8434 8434 codelist{examples/example-gnuplot.py}
8435 8435 \end_inset
8436 8436
8437 8437
8438 8438 \layout Subsection
8439 8439
8440 8440 The
8441 8441 \family typewriter
8442 8442 numeric
8443 8443 \family default
8444 8444 profile: a scientific computing environment
8445 8445 \layout Standard
8446 8446
8447 8447 The
8448 8448 \family typewriter
8449 8449 numeric
8450 8450 \family default
8451 8451 IPython profile, which you can activate with
8452 8452 \family typewriter
8453 8453 `ipython -p numeric
8454 8454 \family default
8455 8455 ' will automatically load the IPython Gnuplot extensions (plus Numeric and
8456 8456 other useful things for numerical computing), contained in the
8457 8457 \family typewriter
8458 8458 IPython.GnuplotInteractive
8459 8459 \family default
8460 8460 module.
8461 8461 This will create the globals
8462 8462 \family typewriter
8463 8463 Gnuplot
8464 8464 \family default
8465 8465 (an alias to the improved Gnuplot2 module),
8466 8466 \family typewriter
8467 8467 gp
8468 8468 \family default
8469 8469 (a Gnuplot active instance), the new magic commands
8470 8470 \family typewriter
8471 8471 %gpc
8472 8472 \family default
8473 8473 and
8474 8474 \family typewriter
8475 8475 %gp_set_instance
8476 8476 \family default
8477 8477 and several other convenient globals.
8478 8478 Type
8479 8479 \family typewriter
8480 8480 gphelp()
8481 8481 \family default
8482 8482 for further details.
8483 8483 \layout Standard
8484 8484
8485 8485 This should turn IPython into a convenient environment for numerical computing,
8486 8486 with all the functions in the NumPy library and the Gnuplot facilities
8487 8487 for plotting.
8488 8488 Further improvements can be obtained by loading the SciPy libraries for
8489 8489 scientific computing, available at
8490 8490 \begin_inset LatexCommand \htmlurl{http://scipy.org}
8491 8491
8492 8492 \end_inset
8493 8493
8494 8494 .
8495 8495 \layout Standard
8496 8496
8497 8497 If you are in the middle of a working session with numerical objects and
8498 8498 need to plot them but you didn't start the
8499 8499 \family typewriter
8500 8500 numeric
8501 8501 \family default
8502 8502 profile, you can load these extensions at any time by typing
8503 8503 \newline
8504 8504
8505 8505 \family typewriter
8506 8506 from IPython.GnuplotInteractive import *
8507 8507 \newline
8508 8508
8509 8509 \family default
8510 8510 at the IPython prompt.
8511 8511 This will allow you to keep your objects intact and start using Gnuplot
8512 8512 to view them.
8513 8513 \layout Section
8514 8514
8515 8515 Reporting bugs
8516 8516 \layout Subsection*
8517 8517
8518 8518 Automatic crash reports
8519 8519 \layout Standard
8520 8520
8521 8521 Ideally, IPython itself shouldn't crash.
8522 8522 It will catch exceptions produced by you, but bugs in its internals will
8523 8523 still crash it.
8524 8524 \layout Standard
8525 8525
8526 8526 In such a situation, IPython will leave a file named
8527 8527 \family typewriter
8528 8528 IPython_crash_report.txt
8529 8529 \family default
8530 8530 in your IPYTHONDIR directory (that way if crashes happen several times
8531 8531 it won't litter many directories, the post-mortem file is always located
8532 8532 in the same place and new occurrences just overwrite the previous one).
8533 8533 If you can mail this file to the developers (see sec.
8534 8534
8535 8535 \begin_inset LatexCommand \ref{sec:credits}
8536 8536
8537 8537 \end_inset
8538 8538
8539 8539 for names and addresses), it will help us
8540 8540 \emph on
8541 8541 a lot
8542 8542 \emph default
8543 8543 in understanding the cause of the problem and fixing it sooner.
8544 8544 \layout Subsection*
8545 8545
8546 8546 The bug tracker
8547 8547 \layout Standard
8548 8548
8549 8549 IPython also has an online bug-tracker, located at
8550 8550 \begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython}
8551 8551
8552 8552 \end_inset
8553 8553
8554 8554 .
8555 8555 In addition to mailing the developers, it would be a good idea to file
8556 8556 a bug report here.
8557 8557 This will ensure that the issue is properly followed to conclusion.
8558 8558 \layout Standard
8559 8559
8560 8560 You can also use this bug tracker to file feature requests.
8561 8561 \layout Section
8562 8562
8563 8563 Brief history
8564 8564 \layout Subsection
8565 8565
8566 8566 Origins
8567 8567 \layout Standard
8568 8568
8569 8569 The current IPython system grew out of the following three projects:
8570 8570 \layout List
8571 8571 \labelwidthstring 00.00.0000
8572 8572
8573 8573 ipython by Fernando P
8574 8574 \begin_inset ERT
8575 8575 status Collapsed
8576 8576
8577 8577 \layout Standard
8578 8578
8579 8579 \backslash
8580 8580 '{e}
8581 8581 \end_inset
8582 8582
8583 8583 rez.
8584 8584 I was working on adding Mathematica-type prompts and a flexible configuration
8585 8585 system (something better than
8586 8586 \family typewriter
8587 8587 $PYTHONSTARTUP
8588 8588 \family default
8589 8589 ) to the standard Python interactive interpreter.
8590 8590 \layout List
8591 8591 \labelwidthstring 00.00.0000
8592 8592
8593 8593 IPP by Janko Hauser.
8594 8594 Very well organized, great usability.
8595 8595 Had an old help system.
8596 8596 IPP was used as the `container' code into which I added the functionality
8597 8597 from ipython and LazyPython.
8598 8598 \layout List
8599 8599 \labelwidthstring 00.00.0000
8600 8600
8601 8601 LazyPython by Nathan Gray.
8602 8602 Simple but
8603 8603 \emph on
8604 8604 very
8605 8605 \emph default
8606 8606 powerful.
8607 8607 The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks
8608 8608 were all taken from here.
8609 8609 \layout Standard
8610 8610
8611 8611 When I found out (see sec.
8612 8612
8613 8613 \begin_inset LatexCommand \ref{figgins}
8614 8614
8615 8615 \end_inset
8616 8616
8617 8617 ) about IPP and LazyPython I tried to join all three into a unified system.
8618 8618 I thought this could provide a very nice working environment, both for
8619 8619 regular programming and scientific computing: shell-like features, IDL/Matlab
8620 8620 numerics, Mathematica-type prompt history and great object introspection
8621 8621 and help facilities.
8622 8622 I think it worked reasonably well, though it was a lot more work than I
8623 8623 had initially planned.
8624 8624 \layout Subsection
8625 8625
8626 8626 Current status
8627 8627 \layout Standard
8628 8628
8629 8629 The above listed features work, and quite well for the most part.
8630 8630 But until a major internal restructuring is done (see below), only bug
8631 8631 fixing will be done, no other features will be added (unless very minor
8632 8632 and well localized in the cleaner parts of the code).
8633 8633 \layout Standard
8634 8634
8635 8635 IPython consists of some 18000 lines of pure python code, of which roughly
8636 8636 two thirds is reasonably clean.
8637 8637 The rest is, messy code which needs a massive restructuring before any
8638 8638 further major work is done.
8639 8639 Even the messy code is fairly well documented though, and most of the problems
8640 8640 in the (non-existent) class design are well pointed to by a PyChecker run.
8641 8641 So the rewriting work isn't that bad, it will just be time-consuming.
8642 8642 \layout Subsection
8643 8643
8644 8644 Future
8645 8645 \layout Standard
8646 8646
8647 8647 See the separate
8648 8648 \family typewriter
8649 8649 new_design
8650 8650 \family default
8651 8651 document for details.
8652 8652 Ultimately, I would like to see IPython become part of the standard Python
8653 8653 distribution as a `big brother with batteries' to the standard Python interacti
8654 8654 ve interpreter.
8655 8655 But that will never happen with the current state of the code, so all contribut
8656 8656 ions are welcome.
8657 8657 \layout Section
8658 8658
8659 8659 License
8660 8660 \layout Standard
8661 8661
8662 8662 IPython is released under the terms of the BSD license, whose general form
8663 8663 can be found at:
8664 8664 \begin_inset LatexCommand \htmlurl{http://www.opensource.org/licenses/bsd-license.php}
8665 8665
8666 8666 \end_inset
8667 8667
8668 8668 .
8669 8669 The full text of the IPython license is reproduced below:
8670 8670 \layout Quote
8671 8671
8672 8672
8673 8673 \family typewriter
8674 8674 \size small
8675 8675 IPython is released under a BSD-type license.
8676 8676 \layout Quote
8677 8677
8678 8678
8679 8679 \family typewriter
8680 8680 \size small
8681 8681 Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez <fperez@colorado.edu>.
8682 8682 \layout Quote
8683 8683
8684 8684
8685 8685 \family typewriter
8686 8686 \size small
8687 8687 Copyright (c) 2001 Janko Hauser <jhauser@zscout.de> and
8688 8688 \newline
8689 8689 Nathaniel Gray <n8gray@caltech.edu>.
8690 8690 \layout Quote
8691 8691
8692 8692
8693 8693 \family typewriter
8694 8694 \size small
8695 8695 All rights reserved.
8696 8696 \layout Quote
8697 8697
8698 8698
8699 8699 \family typewriter
8700 8700 \size small
8701 8701 Redistribution and use in source and binary forms, with or without modification,
8702 8702 are permitted provided that the following conditions are met:
8703 8703 \layout Quote
8704 8704
8705 8705
8706 8706 \family typewriter
8707 8707 \size small
8708 8708 a.
8709 8709 Redistributions of source code must retain the above copyright notice,
8710 8710 this list of conditions and the following disclaimer.
8711 8711 \layout Quote
8712 8712
8713 8713
8714 8714 \family typewriter
8715 8715 \size small
8716 8716 b.
8717 8717 Redistributions in binary form must reproduce the above copyright notice,
8718 8718 this list of conditions and the following disclaimer in the documentation
8719 8719 and/or other materials provided with the distribution.
8720 8720 \layout Quote
8721 8721
8722 8722
8723 8723 \family typewriter
8724 8724 \size small
8725 8725 c.
8726 8726 Neither the name of the copyright holders nor the names of any contributors
8727 8727 to this software may be used to endorse or promote products derived from
8728 8728 this software without specific prior written permission.
8729 8729 \layout Quote
8730 8730
8731 8731
8732 8732 \family typewriter
8733 8733 \size small
8734 8734 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
8735 8735 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
8736 8736 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
8737 8737 PURPOSE ARE DISCLAIMED.
8738 8738 IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
8739 8739 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
8740 8740 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
8741 8741 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
8742 8742 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
8743 8743 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
8744 8744 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
8745 8745
8746 8746 \layout Standard
8747 8747
8748 8748 Individual authors are the holders of the copyright for their code and are
8749 8749 listed in each file.
8750 8750 \layout Standard
8751 8751
8752 8752 Some files (
8753 8753 \family typewriter
8754 8754 DPyGetOpt.py
8755 8755 \family default
8756 8756 , for example) may be licensed under different conditions.
8757 8757 Ultimately each file indicates clearly the conditions under which its author/au
8758 8758 thors have decided to publish the code.
8759 8759 \layout Standard
8760 8760
8761 8761 Versions of IPython up to and including 0.6.3 were released under the GNU
8762 8762 Lesser General Public License (LGPL), available at
8763 8763 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/copyleft/lesser.html}
8764 8764
8765 8765 \end_inset
8766 8766
8767 8767 .
8768 8768 \layout Section
8769 8769
8770 8770
8771 8771 \begin_inset LatexCommand \label{sec:credits}
8772 8772
8773 8773 \end_inset
8774 8774
8775 8775 Credits
8776 8776 \layout Standard
8777 8777
8778 8778 IPython is mainly developed by Fernando P
8779 8779 \begin_inset ERT
8780 8780 status Collapsed
8781 8781
8782 8782 \layout Standard
8783 8783
8784 8784 \backslash
8785 8785 '{e}
8786 8786 \end_inset
8787 8787
8788 8788 rez
8789 8789 \family typewriter
8790 8790 <fperez@colorado.edu>
8791 8791 \family default
8792 8792 , but the project was born from mixing in Fernando's code with the IPP project
8793 8793 by Janko Hauser
8794 8794 \family typewriter
8795 8795 <jhauser-AT-zscout.de>
8796 8796 \family default
8797 8797 and LazyPython by Nathan Gray
8798 8798 \family typewriter
8799 8799 <n8gray-AT-caltech.edu>
8800 8800 \family default
8801 8801 .
8802 8802 For all IPython-related requests, please contact Fernando.
8803 8803
8804 8804 \layout Standard
8805 8805
8806 8806 As of late 2005, the following developers have joined the core team:
8807 8807 \layout List
8808 8808 \labelwidthstring 00.00.0000
8809 8809
8810 8810 Robert\SpecialChar ~
8811 8811 Kern
8812 8812 \family typewriter
8813 8813 <rkern-AT-enthought.com>
8814 8814 \family default
8815 8815 : co-mentored the 2005 Google Summer of Code project to develop python interacti
8816 8816 ve notebooks (XML documents) and graphical interface.
8817 8817 This project was awarded to the students Tzanko Matev
8818 8818 \family typewriter
8819 8819 <tsanko-AT-gmail.com>
8820 8820 \family default
8821 8821 and Toni Alatalo
8822 8822 \family typewriter
8823 8823 <antont-AT-an.org>
8824 8824 \layout List
8825 8825 \labelwidthstring 00.00.0000
8826 8826
8827 8827 Brian\SpecialChar ~
8828 8828 Granger
8829 8829 \family typewriter
8830 8830 <bgranger-AT-scu.edu>
8831 8831 \family default
8832 8832 : extending IPython to allow support for interactive parallel computing.
8833 \layout List
8834 \labelwidthstring 00.00.0000
8835
8836 Ville\SpecialChar ~
8837 Vainio
8838 \family typewriter
8839 <vivainio-AT-gmail.com>
8840 \family default
8841 : Ville is the new maintainer for the main trunk of IPython as of version
8842 0.7.1.
8833 8843 \layout Standard
8834 8844
8835 8845 User or development help should be requested via the IPython mailing lists:
8836 8846 \layout Description
8837 8847
8838 8848 User\SpecialChar ~
8839 8849 list:
8840 8850 \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user}
8841 8851
8842 8852 \end_inset
8843 8853
8844 8854
8845 8855 \layout Description
8846 8856
8847 8857 Developer's\SpecialChar ~
8848 8858 list:
8849 8859 \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev}
8850 8860
8851 8861 \end_inset
8852 8862
8853 8863
8854 8864 \layout Standard
8855 8865
8856 8866 The IPython project is also very grateful to
8857 8867 \begin_inset Foot
8858 8868 collapsed true
8859 8869
8860 8870 \layout Standard
8861 8871
8862 8872 I've mangled email addresses to reduce spam, since the IPython manuals can
8863 8873 be accessed online.
8864 8874 \end_inset
8865 8875
8866 8876 :
8867 8877 \layout Standard
8868 8878
8869 8879 Bill Bumgarner
8870 8880 \family typewriter
8871 8881 <bbum-AT-friday.com>
8872 8882 \family default
8873 8883 : for providing the DPyGetOpt module which gives very powerful and convenient
8874 8884 handling of command-line options (light years ahead of what Python 2.1.1's
8875 8885 getopt module does).
8876 8886 \layout Standard
8877 8887
8878 8888 Ka-Ping Yee
8879 8889 \family typewriter
8880 8890 <ping-AT-lfw.org>
8881 8891 \family default
8882 8892 : for providing the Itpl module for convenient and powerful string interpolation
8883 8893 with a much nicer syntax than formatting through the '%' operator.
8884 8894 \layout Standard
8885 8895
8886 8896 Arnd Baecker
8887 8897 \family typewriter
8888 8898 <baecker-AT-physik.tu-dresden.de>
8889 8899 \family default
8890 8900 : for his many very useful suggestions and comments, and lots of help with
8891 8901 testing and documentation checking.
8892 8902 Many of IPython's newer features are a result of discussions with him (bugs
8893 8903 are still my fault, not his).
8894 8904 \layout Standard
8895 8905
8896 8906 Obviously Guido van\SpecialChar ~
8897 8907 Rossum and the whole Python development team, that goes
8898 8908 without saying.
8899 8909 \layout Standard
8900 8910
8901 8911 IPython's website is generously hosted at
8902 8912 \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}
8903 8913
8904 8914 \end_inset
8905 8915
8906 8916 by Enthought (
8907 8917 \begin_inset LatexCommand \htmlurl{http://www.enthought.com}
8908 8918
8909 8919 \end_inset
8910 8920
8911 8921 ).
8912 8922 I am very grateful to them and all of the SciPy team for their contribution.
8913 8923 \layout Standard
8914 8924
8915 8925
8916 8926 \begin_inset LatexCommand \label{figgins}
8917 8927
8918 8928 \end_inset
8919 8929
8920 8930 Fernando would also like to thank Stephen Figgins
8921 8931 \family typewriter
8922 8932 <fig-AT-monitor.net>
8923 8933 \family default
8924 8934 , an O'Reilly Python editor.
8925 8935 His Oct/11/2001 article about IPP and LazyPython, was what got this project
8926 8936 started.
8927 8937 You can read it at:
8928 8938 \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html}
8929 8939
8930 8940 \end_inset
8931 8941
8932 8942 .
8933 8943 \layout Standard
8934 8944
8935 8945 And last but not least, all the kind IPython users who have emailed new
8936 8946 code, bug reports, fixes, comments and ideas.
8937 8947 A brief list follows, please let me know if I have ommitted your name by
8938 8948 accident:
8939 8949 \layout List
8940 8950 \labelwidthstring 00.00.0000
8941 8951
8942 8952 Jack\SpecialChar ~
8943 8953 Moffit
8944 8954 \family typewriter
8945 8955 <jack-AT-xiph.org>
8946 8956 \family default
8947 8957 Bug fixes, including the infamous color problem.
8948 8958 This bug alone caused many lost hours and frustration, many thanks to him
8949 8959 for the fix.
8950 8960 I've always been a fan of Ogg & friends, now I have one more reason to
8951 8961 like these folks.
8952 8962 \newline
8953 8963 Jack is also contributing with Debian packaging and many other things.
8954 8964 \layout List
8955 8965 \labelwidthstring 00.00.0000
8956 8966
8957 8967 Alexander\SpecialChar ~
8958 8968 Schmolck
8959 8969 \family typewriter
8960 8970 <a.schmolck-AT-gmx.net>
8961 8971 \family default
8962 8972 Emacs work, bug reports, bug fixes, ideas, lots more.
8963 8973 The ipython.el mode for (X)Emacs is Alex's code, providing full support
8964 8974 for IPython under (X)Emacs.
8965 8975 \layout List
8966 8976 \labelwidthstring 00.00.0000
8967 8977
8968 8978 Andrea\SpecialChar ~
8969 8979 Riciputi
8970 8980 \family typewriter
8971 8981 <andrea.riciputi-AT-libero.it>
8972 8982 \family default
8973 8983 Mac OSX information, Fink package management.
8974 8984 \layout List
8975 8985 \labelwidthstring 00.00.0000
8976 8986
8977 8987 Gary\SpecialChar ~
8978 8988 Bishop
8979 8989 \family typewriter
8980 8990 <gb-AT-cs.unc.edu>
8981 8991 \family default
8982 8992 Bug reports, and patches to work around the exception handling idiosyncracies
8983 8993 of WxPython.
8984 8994 Readline and color support for Windows.
8985 8995 \layout List
8986 8996 \labelwidthstring 00.00.0000
8987 8997
8988 8998 Jeffrey\SpecialChar ~
8989 8999 Collins
8990 9000 \family typewriter
8991 9001 <Jeff.Collins-AT-vexcel.com>
8992 9002 \family default
8993 9003 Bug reports.
8994 9004 Much improved readline support, including fixes for Python 2.3.
8995 9005 \layout List
8996 9006 \labelwidthstring 00.00.0000
8997 9007
8998 9008 Dryice\SpecialChar ~
8999 9009 Liu
9000 9010 \family typewriter
9001 9011 <dryice-AT-liu.com.cn>
9002 9012 \family default
9003 9013 FreeBSD port.
9004 9014 \layout List
9005 9015 \labelwidthstring 00.00.0000
9006 9016
9007 9017 Mike\SpecialChar ~
9008 9018 Heeter
9009 9019 \family typewriter
9010 9020 <korora-AT-SDF.LONESTAR.ORG>
9011 9021 \layout List
9012 9022 \labelwidthstring 00.00.0000
9013 9023
9014 9024 Christopher\SpecialChar ~
9015 9025 Hart
9016 9026 \family typewriter
9017 9027 <hart-AT-caltech.edu>
9018 9028 \family default
9019 9029 PDB integration.
9020 9030 \layout List
9021 9031 \labelwidthstring 00.00.0000
9022 9032
9023 9033 Milan\SpecialChar ~
9024 9034 Zamazal
9025 9035 \family typewriter
9026 9036 <pdm-AT-zamazal.org>
9027 9037 \family default
9028 9038 Emacs info.
9029 9039 \layout List
9030 9040 \labelwidthstring 00.00.0000
9031 9041
9032 9042 Philip\SpecialChar ~
9033 9043 Hisley
9034 9044 \family typewriter
9035 9045 <compsys-AT-starpower.net>
9036 9046 \layout List
9037 9047 \labelwidthstring 00.00.0000
9038 9048
9039 9049 Holger\SpecialChar ~
9040 9050 Krekel
9041 9051 \family typewriter
9042 9052 <pyth-AT-devel.trillke.net>
9043 9053 \family default
9044 9054 Tab completion, lots more.
9045 9055 \layout List
9046 9056 \labelwidthstring 00.00.0000
9047 9057
9048 9058 Robin\SpecialChar ~
9049 9059 Siebler
9050 9060 \family typewriter
9051 9061 <robinsiebler-AT-starband.net>
9052 9062 \layout List
9053 9063 \labelwidthstring 00.00.0000
9054 9064
9055 9065 Ralf\SpecialChar ~
9056 9066 Ahlbrink
9057 9067 \family typewriter
9058 9068 <ralf_ahlbrink-AT-web.de>
9059 9069 \layout List
9060 9070 \labelwidthstring 00.00.0000
9061 9071
9062 9072 Thorsten\SpecialChar ~
9063 9073 Kampe
9064 9074 \family typewriter
9065 9075 <thorsten-AT-thorstenkampe.de>
9066 9076 \layout List
9067 9077 \labelwidthstring 00.00.0000
9068 9078
9069 9079 Fredrik\SpecialChar ~
9070 9080 Kant
9071 9081 \family typewriter
9072 9082 <fredrik.kant-AT-front.com>
9073 9083 \family default
9074 9084 Windows setup.
9075 9085 \layout List
9076 9086 \labelwidthstring 00.00.0000
9077 9087
9078 9088 Syver\SpecialChar ~
9079 9089 Enstad
9080 9090 \family typewriter
9081 9091 <syver-en-AT-online.no>
9082 9092 \family default
9083 9093 Windows setup.
9084 9094 \layout List
9085 9095 \labelwidthstring 00.00.0000
9086 9096
9087 9097 Richard
9088 9098 \family typewriter
9089 9099 <rxe-AT-renre-europe.com>
9090 9100 \family default
9091 9101 Global embedding.
9092 9102 \layout List
9093 9103 \labelwidthstring 00.00.0000
9094 9104
9095 9105 Hayden\SpecialChar ~
9096 9106 Callow
9097 9107 \family typewriter
9098 9108 <h.callow-AT-elec.canterbury.ac.nz>
9099 9109 \family default
9100 9110 Gnuplot.py 1.6 compatibility.
9101 9111 \layout List
9102 9112 \labelwidthstring 00.00.0000
9103 9113
9104 9114 Leonardo\SpecialChar ~
9105 9115 Santagada
9106 9116 \family typewriter
9107 9117 <retype-AT-terra.com.br>
9108 9118 \family default
9109 9119 Fixes for Windows installation.
9110 9120 \layout List
9111 9121 \labelwidthstring 00.00.0000
9112 9122
9113 9123 Christopher\SpecialChar ~
9114 9124 Armstrong
9115 9125 \family typewriter
9116 9126 <radix-AT-twistedmatrix.com>
9117 9127 \family default
9118 9128 Bugfixes.
9119 9129 \layout List
9120 9130 \labelwidthstring 00.00.0000
9121 9131
9122 9132 Francois\SpecialChar ~
9123 9133 Pinard
9124 9134 \family typewriter
9125 9135 <pinard-AT-iro.umontreal.ca>
9126 9136 \family default
9127 9137 Code and documentation fixes.
9128 9138 \layout List
9129 9139 \labelwidthstring 00.00.0000
9130 9140
9131 9141 Cory\SpecialChar ~
9132 9142 Dodt
9133 9143 \family typewriter
9134 9144 <cdodt-AT-fcoe.k12.ca.us>
9135 9145 \family default
9136 9146 Bug reports and Windows ideas.
9137 9147 Patches for Windows installer.
9138 9148 \layout List
9139 9149 \labelwidthstring 00.00.0000
9140 9150
9141 9151 Olivier\SpecialChar ~
9142 9152 Aubert
9143 9153 \family typewriter
9144 9154 <oaubert-AT-bat710.univ-lyon1.fr>
9145 9155 \family default
9146 9156 New magics.
9147 9157 \layout List
9148 9158 \labelwidthstring 00.00.0000
9149 9159
9150 9160 King\SpecialChar ~
9151 9161 C.\SpecialChar ~
9152 9162 Shu
9153 9163 \family typewriter
9154 9164 <kingshu-AT-myrealbox.com>
9155 9165 \family default
9156 9166 Autoindent patch.
9157 9167 \layout List
9158 9168 \labelwidthstring 00.00.0000
9159 9169
9160 9170 Chris\SpecialChar ~
9161 9171 Drexler
9162 9172 \family typewriter
9163 9173 <chris-AT-ac-drexler.de>
9164 9174 \family default
9165 9175 Readline packages for Win32/CygWin.
9166 9176 \layout List
9167 9177 \labelwidthstring 00.00.0000
9168 9178
9169 9179 Gustavo\SpecialChar ~
9170 9180 Cordova\SpecialChar ~
9171 9181 Avila
9172 9182 \family typewriter
9173 9183 <gcordova-AT-sismex.com>
9174 9184 \family default
9175 9185 EvalDict code for nice, lightweight string interpolation.
9176 9186 \layout List
9177 9187 \labelwidthstring 00.00.0000
9178 9188
9179 9189 Kasper\SpecialChar ~
9180 9190 Souren
9181 9191 \family typewriter
9182 9192 <Kasper.Souren-AT-ircam.fr>
9183 9193 \family default
9184 9194 Bug reports, ideas.
9185 9195 \layout List
9186 9196 \labelwidthstring 00.00.0000
9187 9197
9188 9198 Gever\SpecialChar ~
9189 9199 Tulley
9190 9200 \family typewriter
9191 9201 <gever-AT-helium.com>
9192 9202 \family default
9193 9203 Code contributions.
9194 9204 \layout List
9195 9205 \labelwidthstring 00.00.0000
9196 9206
9197 9207 Ralf\SpecialChar ~
9198 9208 Schmitt
9199 9209 \family typewriter
9200 9210 <ralf-AT-brainbot.com>
9201 9211 \family default
9202 9212 Bug reports & fixes.
9203 9213 \layout List
9204 9214 \labelwidthstring 00.00.0000
9205 9215
9206 9216 Oliver\SpecialChar ~
9207 9217 Sander
9208 9218 \family typewriter
9209 9219 <osander-AT-gmx.de>
9210 9220 \family default
9211 9221 Bug reports.
9212 9222 \layout List
9213 9223 \labelwidthstring 00.00.0000
9214 9224
9215 9225 Rod\SpecialChar ~
9216 9226 Holland
9217 9227 \family typewriter
9218 9228 <rhh-AT-structurelabs.com>
9219 9229 \family default
9220 9230 Bug reports and fixes to logging module.
9221 9231 \layout List
9222 9232 \labelwidthstring 00.00.0000
9223 9233
9224 9234 Daniel\SpecialChar ~
9225 9235 'Dang'\SpecialChar ~
9226 9236 Griffith
9227 9237 \family typewriter
9228 9238 <pythondev-dang-AT-lazytwinacres.net>
9229 9239 \family default
9230 9240 Fixes, enhancement suggestions for system shell use.
9231 9241 \layout List
9232 9242 \labelwidthstring 00.00.0000
9233 9243
9234 9244 Viktor\SpecialChar ~
9235 9245 Ransmayr
9236 9246 \family typewriter
9237 9247 <viktor.ransmayr-AT-t-online.de>
9238 9248 \family default
9239 9249 Tests and reports on Windows installation issues.
9240 9250 Contributed a true Windows binary installer.
9241 9251 \layout List
9242 9252 \labelwidthstring 00.00.0000
9243 9253
9244 9254 Mike\SpecialChar ~
9245 9255 Salib
9246 9256 \family typewriter
9247 9257 <msalib-AT-mit.edu>
9248 9258 \family default
9249 9259 Help fixing a subtle bug related to traceback printing.
9250 9260 \layout List
9251 9261 \labelwidthstring 00.00.0000
9252 9262
9253 9263 W.J.\SpecialChar ~
9254 9264 van\SpecialChar ~
9255 9265 der\SpecialChar ~
9256 9266 Laan
9257 9267 \family typewriter
9258 9268 <gnufnork-AT-hetdigitalegat.nl>
9259 9269 \family default
9260 9270 Bash-like prompt specials.
9261 9271 \layout List
9262 9272 \labelwidthstring 00.00.0000
9263 9273
9264 Ville\SpecialChar ~
9265 Vainio
9266 \family typewriter
9267 <vivainio-AT-kolumbus.fi>
9268 \family default
9269 Bugfixes and suggestions.
9270 Excellent patches for many new features.
9271 \layout List
9272 \labelwidthstring 00.00.0000
9273
9274 9274 Antoon\SpecialChar ~
9275 9275 Pardon
9276 9276 \family typewriter
9277 9277 <Antoon.Pardon-AT-rece.vub.ac.be>
9278 9278 \family default
9279 9279 Critical fix for the multithreaded IPython.
9280 9280 \layout List
9281 9281 \labelwidthstring 00.00.0000
9282 9282
9283 9283 John\SpecialChar ~
9284 9284 Hunter
9285 9285 \family typewriter
9286 9286 <jdhunter-AT-nitace.bsd.uchicago.edu>
9287 9287 \family default
9288 9288 Matplotlib author, helped with all the development of support for matplotlib
9289 9289 in IPyhton, including making necessary changes to matplotlib itself.
9290 9290 \layout List
9291 9291 \labelwidthstring 00.00.0000
9292 9292
9293 9293 Matthew\SpecialChar ~
9294 9294 Arnison
9295 9295 \family typewriter
9296 9296 <maffew-AT-cat.org.au>
9297 9297 \family default
9298 9298 Bug reports, `
9299 9299 \family typewriter
9300 9300 %run -d
9301 9301 \family default
9302 9302 ' idea.
9303 9303 \layout List
9304 9304 \labelwidthstring 00.00.0000
9305 9305
9306 9306 Prabhu\SpecialChar ~
9307 9307 Ramachandran
9308 9308 \family typewriter
9309 9309 <prabhu_r-AT-users.sourceforge.net>
9310 9310 \family default
9311 9311 Help with (X)Emacs support, threading patches, ideas...
9312 9312 \layout List
9313 9313 \labelwidthstring 00.00.0000
9314 9314
9315 9315 Norbert\SpecialChar ~
9316 9316 Tretkowski
9317 9317 \family typewriter
9318 9318 <tretkowski-AT-inittab.de>
9319 9319 \family default
9320 9320 help with Debian packaging and distribution.
9321 9321 \layout List
9322 9322 \labelwidthstring 00.00.0000
9323 9323
9324 9324 George\SpecialChar ~
9325 9325 Sakkis <
9326 9326 \family typewriter
9327 9327 gsakkis-AT-eden.rutgers.edu>
9328 9328 \family default
9329 9329 New matcher for tab-completing named arguments of user-defined functions.
9330 9330 \layout List
9331 9331 \labelwidthstring 00.00.0000
9332 9332
9333 9333 J�rgen\SpecialChar ~
9334 9334 Stenarson
9335 9335 \family typewriter
9336 9336 <jorgen.stenarson-AT-bostream.nu>
9337 9337 \family default
9338 9338 Wildcard support implementation for searching namespaces.
9339 9339 \layout List
9340 9340 \labelwidthstring 00.00.0000
9341 9341
9342 9342 Vivian\SpecialChar ~
9343 9343 De\SpecialChar ~
9344 9344 Smedt
9345 9345 \family typewriter
9346 9346 <vivian-AT-vdesmedt.com>
9347 9347 \family default
9348 9348 Debugger enhancements, so that when pdb is activated from within IPython,
9349 9349 coloring, tab completion and other features continue to work seamlessly.
9350 9350 \layout List
9351 9351 \labelwidthstring 00.00.0000
9352 9352
9353 9353 Scott\SpecialChar ~
9354 9354 Tsai
9355 9355 \family typewriter
9356 9356 <scottt958-AT-yahoo.com.tw>
9357 9357 \family default
9358 9358 Support for automatic editor invocation on syntax errors (see
9359 9359 \begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython/issue36}
9360 9360
9361 9361 \end_inset
9362 9362
9363 9363 ).
9364 9364 \layout List
9365 9365 \labelwidthstring 00.00.0000
9366 9366
9367 9367 Alexander\SpecialChar ~
9368 9368 Belchenko
9369 9369 \family typewriter
9370 9370 <bialix-AT-ukr.net>
9371 9371 \family default
9372 9372 Improvements for win32 paging system.
9373 9373 \the_end
General Comments 0
You need to be logged in to leave comments. Login now