##// END OF EJS Templates
Manual updates
fperez -
r33:d9100225
parent child
Show More
@@ -6,7 +6,7 Requires Python 2.1 or better.
6
6
7 This file contains the main make_IPython() starter function.
7 This file contains the main make_IPython() starter function.
8
8
9 $Id: ipmaker.py 802 2005-09-06 03:49:12Z fperez $"""
9 $Id: ipmaker.py 911 2005-10-08 07:59:40Z fperez $"""
10
10
11 #*****************************************************************************
11 #*****************************************************************************
12 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
12 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
@@ -112,7 +112,9 object? -> Details about 'object'. ?object also works, ?? prints more.
112
112
113 IP.usage = interactive_usage
113 IP.usage = interactive_usage
114
114
115 # Platform-dependent suffix and directory names
115 # Platform-dependent suffix and directory names. We use _ipython instead
116 # of .ipython under win32 b/c there's software that breaks with .named
117 # directories on that platform.
116 if os.name == 'posix':
118 if os.name == 'posix':
117 rc_suffix = ''
119 rc_suffix = ''
118 ipdir_def = '.ipython'
120 ipdir_def = '.ipython'
@@ -35,6 +35,15
35
35
36 % This helps prevent overly long lines that stretch beyond the margins
36 % This helps prevent overly long lines that stretch beyond the margins
37 \sloppy
37 \sloppy
38
39 % Define a \codelist command which either uses listings for latex, or
40 % plain verbatim for html (since latex2html doesn't understand the
41 % listings package).
42 \usepackage{verbatim}
43 \newcommand{\codelist}[1] {
44 \latex{\lstinputlisting{#1}}
45 \html{\verbatiminput{#1}}
46 }
38 \end_preamble
47 \end_preamble
39 \language english
48 \language english
40 \inputencoding latin1
49 \inputencoding latin1
@@ -523,21 +532,6 See the notes in sec.
523 Detailed Unix instructions (Linux, Mac OS X, etc.)
532 Detailed Unix instructions (Linux, Mac OS X, etc.)
524 \layout Standard
533 \layout Standard
525
534
526
527 \begin_inset ERT
528 status Open
529
530 \layout Standard
531
532 \backslash
533 html{
534 \backslash
535 textbf{A warning to readers of the HTML version of this manual}: all options below are preceded with with TWO dashes and no intervening space between the dashes (e.g. Dash-Dash-home). The default HTML conversion tools mangle these into a single dash.}
536 \end_inset
537
538
539 \layout Standard
540
541 For RPM based systems, simply install the supplied package in the usual
535 For RPM based systems, simply install the supplied package in the usual
542 manner.
536 manner.
543 If you download the tar archive, the process is:
537 If you download the tar archive, the process is:
@@ -604,39 +598,41 $ python setup.py install
604 Note that this assumes you have root access to your machine.
598 Note that this assumes you have root access to your machine.
605 If you don't have root access or don't want IPython to go in the default
599 If you don't have root access or don't want IPython to go in the default
606 python directories, you'll need to use the
600 python directories, you'll need to use the
607 \family typewriter
601 \begin_inset ERT
608 --home
602 status Collapsed
609 \family default
603
604 \layout Standard
605
606 \backslash
607 verb|--home|
608 \end_inset
609
610 option (or
610 option (or
611 \family typewriter
611 \begin_inset ERT
612 --prefix
612 status Collapsed
613 \family default
613
614 \layout Standard
615
616 \backslash
617 verb|--prefix|
618 \end_inset
619
614 ).
620 ).
615 For example:
621 For example:
616 \newline
622 \newline
617
623
618 \family typewriter
624 \begin_inset ERT
619 $ python setup.py install --home $HOME/local
625 status Collapsed
620 \family default
621
622 \newline
623 will install
624 \begin_inset Foot
625 collapsed true
626
626
627 \layout Standard
627 \layout Standard
628
628
629 If you are reading these instructions in HTML format, please note that the
629 \backslash
630 option is --home, with
630 verb|$ python setup.py install --home $HOME/local|
631 \emph on
632 two
633 \emph default
634 dashes.
635 The automatic HTML conversion program seems to eat up one of the dashes,
636 unfortunately (it's ok in the PDF version).
637 \end_inset
631 \end_inset
638
632
639 IPython into
633
634 \newline
635 will install IPython into
640 \family typewriter
636 \family typewriter
641 $HOME/local
637 $HOME/local
642 \family default
638 \family default
@@ -645,17 +641,29 and its subdirectories (creating them if necessary).
645 You can type
641 You can type
646 \newline
642 \newline
647
643
648 \family typewriter
644 \begin_inset ERT
649 $ python setup.py --help
645 status Collapsed
650 \family default
651
646
647 \layout Standard
648
649 \backslash
650 verb|$ python setup.py --help|
651 \end_inset
652
653
652 \newline
654 \newline
653 for more details.
655 for more details.
654 \newline
656 \newline
655 Note that if you change the default location for
657 Note that if you change the default location for
656 \family typewriter
658 \begin_inset ERT
657 --home
659 status Collapsed
658 \family default
660
661 \layout Standard
662
663 \backslash
664 verb|--home|
665 \end_inset
666
659 at installation, IPython may end up installed at a location which is not
667 at installation, IPython may end up installed at a location which is not
660 part of your
668 part of your
661 \family typewriter
669 \family typewriter
@@ -668,9 +676,15 $PYTHONPATH
668 IPython/
676 IPython/
669 \family default
677 \family default
670 directory ended (typically the value you give to
678 directory ended (typically the value you give to
671 \family typewriter
679 \begin_inset ERT
672 --home
680 status Collapsed
673 \family default
681
682 \layout Standard
683
684 \backslash
685 verb|--home|
686 \end_inset
687
674 plus
688 plus
675 \family typewriter
689 \family typewriter
676 /lib/python
690 /lib/python
@@ -698,6 +712,15 Under OSX, there is a choice you need to make.
698 users who favor each of the approaches.
712 users who favor each of the approaches.
699 Here I will simply list the known installation issues under OSX, along
713 Here I will simply list the known installation issues under OSX, along
700 with their solutions.
714 with their solutions.
715 \layout Standard
716
717 This page:
718 \begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html}
719
720 \end_inset
721
722 contains information on this topic, with additional details on how to make
723 IPython and matplotlib play nicely under OSX.
701 \layout Subsubsection*
724 \layout Subsubsection*
702
725
703 GUI problems
726 GUI problems
@@ -716,7 +739,7 The following instructions apply to an install of IPython under OSX from
716
739
717 IPython offers various forms of support for interacting with graphical applicati
740 IPython offers various forms of support for interacting with graphical applicati
718 ons from the command line, from simple Tk apps (which are in principle always
741 ons from the command line, from simple Tk apps (which are in principle always
719 supported by Python) to interactive control of WX, QT and GTK apps.
742 supported by Python) to interactive control of WX, Qt and GTK apps.
720 Under OSX, however, this requires that ipython is installed by calling
743 Under OSX, however, this requires that ipython is installed by calling
721 the special
744 the special
722 \family typewriter
745 \family typewriter
@@ -726,38 +749,38 pythonw
726 Apple's graphical environment.
749 Apple's graphical environment.
727 \layout Standard
750 \layout Standard
728
751
729 So when installing under OSX, it is best to use the following command
752 So when installing under OSX, it is best to use the following command:
753 \family typewriter
754
755 \newline
756
757 \family default
758
730 \begin_inset ERT
759 \begin_inset ERT
731 status Collapsed
760 status Collapsed
732
761
733 \layout Standard
762 \layout Standard
734
763
735 \backslash
764 \backslash
736 html{
765 verb| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
737 \backslash
738 emph{[Again, in the HTML manual, the option is called -~-install=scripts, with TWO dashes and no intervening space between the dashes]}}
739 \end_inset
766 \end_inset
740
767
741 :
742 \family typewriter
743
768
744 \newline
769 \newline
745 \SpecialChar ~
770 or
746 \SpecialChar ~
747 $ sudo pythonw setup.py install --install-scripts=/usr/local/bin
748 \family default
749
750 \newline
771 \newline
751 or
752 \family typewriter
753
772
754 \newline
773 \begin_inset ERT
755 \SpecialChar ~
774 status Open
756 \SpecialChar ~
757 $ sudo pythonw setup.py install --install-scripts=/usr/bin
758 \newline
759
775
760 \family default
776 \layout Standard
777
778 \backslash
779 verb| $ sudo pythonw setup.py install --install-scripts=/usr/bin|
780 \end_inset
781
782
783 \newline
761 depending on where you like to keep hand-installed executables.
784 depending on where you like to keep hand-installed executables.
762 \layout Standard
785 \layout Standard
763
786
@@ -786,9 +809,15 setup.py
786 \layout Standard
809 \layout Standard
787
810
788 It is also a good idea to use the special flag
811 It is also a good idea to use the special flag
789 \family typewriter
812 \begin_inset ERT
790 --install-scripts
813 status Collapsed
791 \family default
814
815 \layout Standard
816
817 \backslash
818 verb|--install-scripts|
819 \end_inset
820
792 as indicated above, to ensure that the ipython scripts end up in a location
821 as indicated above, to ensure that the ipython scripts end up in a location
793 which is part of your
822 which is part of your
794 \family typewriter
823 \family typewriter
@@ -1147,7 +1176,7 Documents and Settings
1147 \backslash
1176 \backslash
1148 YourUserName
1177 YourUserName
1149 \backslash
1178 \backslash
1150 .ipython
1179 _ipython
1151 \family default
1180 \family default
1152 , and Win 9x users under
1181 , and Win 9x users under
1153 \family typewriter
1182 \family typewriter
@@ -1157,7 +1186,7 Program Files
1157 \backslash
1186 \backslash
1158 IPython
1187 IPython
1159 \backslash
1188 \backslash
1160 .ipython.
1189 _ipython.
1161 \layout Section
1190 \layout Section
1162
1191
1163
1192
@@ -2393,6 +2422,7 The following special options are ONLY valid at the beginning of the command
2393 \family typewriter
2422 \family typewriter
2394 \series bold
2423 \series bold
2395 -gthread,\SpecialChar ~
2424 -gthread,\SpecialChar ~
2425 -qthread,\SpecialChar ~
2396 -wthread,\SpecialChar ~
2426 -wthread,\SpecialChar ~
2397 -pylab:
2427 -pylab:
2398 \family default
2428 \family default
@@ -2403,29 +2433,18 one
2403 \emph default
2433 \emph default
2404 of these can be given, and it can only be given as the first option passed
2434 of these can be given, and it can only be given as the first option passed
2405 to IPython (it will have no effect in any other position).
2435 to IPython (it will have no effect in any other position).
2406 They provide threading support for the GTK and WXPython toolkits, and for
2436 They provide threading support for the GTK Qt and WXPython toolkits, and
2407 the matplotlib library.
2437 for the matplotlib library.
2408 \layout List
2438 \layout List
2409 \labelwidthstring 00.00.0000
2439 \labelwidthstring 00.00.0000
2410
2440
2411 \SpecialChar ~
2441 \SpecialChar ~
2412 If
2442 With any of the first three options, IPython starts running a separate
2413 \family typewriter
2443 thread for the graphical toolkit's operation, so that you can open and
2414 -gthread
2444 control graphical elements from within an IPython command line, without
2415 \family default
2445 blocking.
2416 is given, IPython starts running a separate thread for GTK operation, so
2446 All three provide essentially the same functionality, respectively for
2417 that pyGTK-based programs can open and control GUIs without blocking IPython.
2447 GTK, QT and WXWidgets (via their Python interfaces).
2418
2419 \layout List
2420 \labelwidthstring 00.00.0000
2421
2422 \SpecialChar ~
2423 Similarly,
2424 \family typewriter
2425 -wthread
2426 \family default
2427 instantiates IPython with threading support for the WXPython toolkit.
2428 You can control WX application windows from within IPython.
2429 \layout List
2448 \layout List
2430 \labelwidthstring 00.00.0000
2449 \labelwidthstring 00.00.0000
2431
2450
@@ -2434,14 +2453,18 one
2434 \family typewriter
2453 \family typewriter
2435 -pylab
2454 -pylab
2436 \family default
2455 \family default
2437 is given, IPython loads special support for the mat- plotlib library (
2456 is given, IPython loads special support for the mat plotlib library (
2438 \begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}
2457 \begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}
2439
2458
2440 \end_inset
2459 \end_inset
2441
2460
2442 ), allowing interactive usage of any of its backends as defined in the user's
2461 ), allowing interactive usage of any of its backends as defined in the user's
2443 .matplotlibrc file.
2462
2444 It automatically activates GTK or WX threading for IPyhton if the choice
2463 \family typewriter
2464 ~/.matplotlib/matplotlibrc
2465 \family default
2466 file.
2467 It automatically activates GTK, Qt or WX threading for IPyhton if the choice
2445 of matplotlib backend requires it.
2468 of matplotlib backend requires it.
2446 It also modifies the
2469 It also modifies the
2447 \family typewriter
2470 \family typewriter
@@ -2465,17 +2488,17 show()
2465 \series default
2488 \series default
2466 The
2489 The
2467 \family typewriter
2490 \family typewriter
2468 -g/wthread
2491 -g/q/wthread
2469 \family default
2492 \family default
2470 options, and
2493 options, and
2471 \family typewriter
2494 \family typewriter
2472 -pylab
2495 -pylab
2473 \family default
2496 \family default
2474 (if matplotlib is configured to use WX or GTK), will normally block Tk
2497 (if matplotlib is configured to use GTK, Qt or WX), will normally block
2475 graphical interfaces.
2498 Tk graphical interfaces.
2476 This means that when either GTK or WX threading is active, any attempt
2499 This means that when either GTK, Qt or WX threading is active, any attempt
2477 to open a Tk GUI will result in a dead window, and pos- sibly cause the
2500 to open a Tk GUI will result in a dead window, and possibly cause the Python
2478 Python interpreter to crash.
2501 interpreter to crash.
2479 An extra option,
2502 An extra option,
2480 \family typewriter
2503 \family typewriter
2481 -tk
2504 -tk
@@ -2510,12 +2533,12 second
2510 \family typewriter
2533 \family typewriter
2511 -tk
2534 -tk
2512 \family default
2535 \family default
2513 is given, IPython will try to coordinate Tk threading with WX or GTK.
2536 is given, IPython will try to coordinate Tk threading with GTK, Qt or WX.
2514 This is however potentially unreliable, and you will have to test on your
2537 This is however potentially unreliable, and you will have to test on your
2515 platform and Python configuration to determine whether it works for you.
2538 platform and Python configuration to determine whether it works for you.
2516 Debian users have reported success, apparently due to the fact that Debian
2539 Debian users have reported success, apparently due to the fact that Debian
2517 builds all of Tcl, Tk, Tkinter and Python with pthreads support.
2540 builds all of Tcl, Tk, Tkinter and Python with pthreads support.
2518 Under other Linux environments (such as Fedora Core 2), this option has
2541 Under other Linux environments (such as Fedora Core 2/3), this option has
2519 caused random crashes and lockups of the Python interpreter.
2542 caused random crashes and lockups of the Python interpreter.
2520 Under other operating systems (Mac OSX and Windows), you'll need to try
2543 Under other operating systems (Mac OSX and Windows), you'll need to try
2521 it to find out, since currently no user reports are available.
2544 it to find out, since currently no user reports are available.
@@ -3626,7 +3649,7 status Open
3626 \layout Standard
3649 \layout Standard
3627
3650
3628 \backslash
3651 \backslash
3629 lstinputlisting{examples/example-magic.py}
3652 codelist{examples/example-magic.py}
3630 \end_inset
3653 \end_inset
3631
3654
3632
3655
@@ -5376,7 +5399,7 status Open
5376 \layout Standard
5399 \layout Standard
5377
5400
5378 \backslash
5401 \backslash
5379 lstinputlisting{../IPython/UserConfig/ipythonrc}
5402 codelist{../IPython/UserConfig/ipythonrc}
5380 \end_inset
5403 \end_inset
5381
5404
5382
5405
@@ -6078,7 +6101,7 status Open
6078 \layout Standard
6101 \layout Standard
6079
6102
6080 \backslash
6103 \backslash
6081 lstinputlisting{examples/example-embed.py}
6104 codelist{examples/example-embed.py}
6082 \end_inset
6105 \end_inset
6083
6106
6084
6107
@@ -6095,7 +6118,7 status Open
6095 \layout Standard
6118 \layout Standard
6096
6119
6097 \backslash
6120 \backslash
6098 lstinputlisting{examples/example-embed-short.py}
6121 codelist{examples/example-embed-short.py}
6099 \end_inset
6122 \end_inset
6100
6123
6101
6124
@@ -7532,6 +7555,10 IPython, via the
7532 \family typewriter
7555 \family typewriter
7533 -gthread
7556 -gthread
7534 \family default
7557 \family default
7558 ,
7559 \family typewriter
7560 -qthread
7561 \family default
7535 and
7562 and
7536 \family typewriter
7563 \family typewriter
7537 -wthread
7564 -wthread
@@ -7542,11 +7569,11 IPython, via the
7542
7569
7543 \end_inset
7570 \end_inset
7544
7571
7545 ), can run in multithreaded mode to support pyGTK and WXPython applications
7572 ), can run in multithreaded mode to support pyGTK, Qt and WXPython applications
7546 respectively.
7573 respectively.
7547 Both of these GUI toolkits need to control the python main loop of execution,
7574 These GUI toolkits need to control the python main loop of execution, so
7548 so under a normal Python interpreter, starting a pyGTK (or WXPython) applicatio
7575 under a normal Python interpreter, starting a pyGTK, Qt or WXPython application
7549 n will immediately freeze the shell.
7576 will immediately freeze the shell.
7550
7577
7551 \layout Standard
7578 \layout Standard
7552
7579
@@ -7557,6 +7584,15 IPython, with one of these options (you can only use one at a time), separates
7557 %run
7584 %run
7558 \family default
7585 \family default
7559 , for example) your GUI code without blocking.
7586 , for example) your GUI code without blocking.
7587 \layout Standard
7588
7589 A nice mini-tutorial on using IPython along with the Qt Designer application
7590 is available at the SciPy wiki:
7591 \begin_inset LatexCommand \htmlurl{http://www.scipy.org/wikis/topical_software/QtWithIPythonAndDesigner}
7592
7593 \end_inset
7594
7595 .
7560 \layout Subsection
7596 \layout Subsection
7561
7597
7562 Tk issues
7598 Tk issues
@@ -7573,18 +7609,18 As indicated in Sec.\SpecialChar ~
7573 -tk
7609 -tk
7574 \family default
7610 \family default
7575 option is provided to try and allow Tk graphical applications to coexist
7611 option is provided to try and allow Tk graphical applications to coexist
7576 interactively with WX or GTK ones.
7612 interactively with WX, Qt or GTK ones.
7577 Whether this works at all, however, is very platform and configuration
7613 Whether this works at all, however, is very platform and configuration
7578 dependent.
7614 dependent.
7579 Please experiment with simple test cases before committing to using this
7615 Please experiment with simple test cases before committing to using this
7580 combination of Tk and WX/GTK threading in a production environment.
7616 combination of Tk and GTK/Qt/WX threading in a production environment.
7581 \layout Subsection
7617 \layout Subsection
7582
7618
7583 Signals and Threads
7619 Signals and Threads
7584 \layout Standard
7620 \layout Standard
7585
7621
7586 When any of the thread systems (WX or GTK) are active, either directly or
7622 When any of the thread systems (GTK, Qt or WX) are active, either directly
7587 via
7623 or via
7588 \family typewriter
7624 \family typewriter
7589 -pylab
7625 -pylab
7590 \family default
7626 \family default
@@ -7714,7 +7750,7 This is obviously a brute force way of avoiding race conditions with the
7714 Interactive demos with IPython
7750 Interactive demos with IPython
7715 \layout Standard
7751 \layout Standard
7716
7752
7717 IPython ships with
7753 IPython ships with XXX
7718 \layout Standard
7754 \layout Standard
7719
7755
7720
7756
@@ -7724,7 +7760,7 status Open
7724 \layout Standard
7760 \layout Standard
7725
7761
7726 \backslash
7762 \backslash
7727 lstinputlisting{examples/example-demo.py}
7763 codelist{examples/example-demo.py}
7728 \end_inset
7764 \end_inset
7729
7765
7730
7766
@@ -8049,7 +8085,7 status Open
8049 \layout Standard
8085 \layout Standard
8050
8086
8051 \backslash
8087 \backslash
8052 lstinputlisting{examples/example-gnuplot.py}
8088 codelist{examples/example-gnuplot.py}
8053 \end_inset
8089 \end_inset
8054
8090
8055
8091
@@ -8188,7 +8224,7 The current IPython system grew out of the following three projects:
8188 \layout List
8224 \layout List
8189 \labelwidthstring 00.00.0000
8225 \labelwidthstring 00.00.0000
8190
8226
8191 ipython by Fernando Prez.
8227 ipython by Fernando Pérez.
8192 I was working on adding Mathematica-type prompts and a flexible configuration
8228 I was working on adding Mathematica-type prompts and a flexible configuration
8193 system (something better than
8229 system (something better than
8194 \family typewriter
8230 \family typewriter
@@ -8383,7 +8419,7 Versions of IPython up to and including 0.6.3 were released under the GNU
8383 Credits
8419 Credits
8384 \layout Standard
8420 \layout Standard
8385
8421
8386 IPython is mainly developed by Fernando Prez
8422 IPython is mainly developed by Fernando Pérez
8387 \family typewriter
8423 \family typewriter
8388 <fperez@colorado.edu>
8424 <fperez@colorado.edu>
8389 \family default
8425 \family default
@@ -8481,7 +8517,7 Ka-Ping Yee
8481 with a much nicer syntax than formatting through the '%' operator.
8517 with a much nicer syntax than formatting through the '%' operator.
8482 \layout Standard
8518 \layout Standard
8483
8519
8484 Arnd Bcker
8520 Arnd Bäcker
8485 \family typewriter
8521 \family typewriter
8486 <baecker-AT-physik.tu-dresden.de>
8522 <baecker-AT-physik.tu-dresden.de>
8487 \family default
8523 \family default
@@ -8765,7 +8801,7 Drexler
8765 \labelwidthstring 00.00.0000
8801 \labelwidthstring 00.00.0000
8766
8802
8767 Gustavo\SpecialChar ~
8803 Gustavo\SpecialChar ~
8768 Crdova\SpecialChar ~
8804 Córdova\SpecialChar ~
8769 Avila
8805 Avila
8770 \family typewriter
8806 \family typewriter
8771 <gcordova-AT-sismex.com>
8807 <gcordova-AT-sismex.com>
General Comments 0
You need to be logged in to leave comments. Login now