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