##// END OF EJS Templates
Work on documentation....
Brian Granger -
Show More
1 NO CONTENT: new file 100644
@@ -0,0 +1,191 b''
1 How to contribute to IPython
2 ============================
3
4 IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
5 This makes it easy for people to contribute to the development of IPython.
6 There are several ways in which you can join in.
7
8 If you have a small change that you want to send to the team, you can edit your
9 bazaar checkout of IPython (see below) in-place, and ask bazaar for the
10 differences::
11
12 $ cd /path/to/your/copy/of/ipython
13 $ bzr diff > my_fixes.diff
14
15 This produces a patch file with your fixes, which we can apply to the source
16 tree. This file should then be attached to a ticket in our `bug tracker
17 <https://bugs.launchpad.net/ipython>`_, indicating what it does.
18
19 This model of creating small, self-contained patches works very well and there
20 are open source projects that do their entire development this way. However,
21 in IPython we have found that for tracking larger changes, making use of
22 bazaar's full capabilities in conjunction with Launchpad's code hosting
23 services makes for a much better experience.
24
25 Making your own branch of IPython allows you to refine your changes over time,
26 track the development of the main team, and propose your own full version of
27 the code for others to use and review, with a minimum amount of fuss. The next
28 parts of this document will explain how to do this.
29
30 Install Bazaar and create a Launchpad account
31 ---------------------------------------------
32
33 First make sure you have installed Bazaar (see their `website
34 <http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
35 you, try the following::
36
37 $ bzr whoami
38 Joe Coder <jcoder@gmail.com>
39
40 This should display your name and email. Next, you will want to create an
41 account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
42 ssh keys. For more information of setting up your ssh keys, see `this link
43 <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
44
45 Get the main IPython branch from Launchpad
46 ------------------------------------------
47
48 Now, you can get a copy of the main IPython development branch (we call this
49 the "trunk")::
50
51 $ bzr branch lp:ipython
52
53 Create a working branch
54 -----------------------
55
56 When working on IPython, you won't actually make edits directly to the
57 :file:`lp:ipython` branch. Instead, you will create a separate branch for your
58 changes. For now, let's assume you want to do your work in a branch named
59 "ipython-mybranch". Create this branch by doing::
60
61 $ bzr branch ipython ipython-mybranch
62
63 When you actually create a branch, you will want to give it a name that
64 reflects the nature of the work that you will be doing in it, like
65 "install-docs-update".
66
67 Make edits in your working branch
68 ---------------------------------
69
70 Now you are ready to actually make edits in your :file:`ipython-mybranch`
71 branch. Before doing this, it is helpful to install this branch so you can
72 test your changes as you work. This is easiest if you have setuptools
73 installed. Then, just do::
74
75 $ cd ipython-mybranch
76 $ python setupegg.py develop
77
78 Now, make some changes. After a while, you will want to commit your changes.
79 This let's Bazaar know that you like the changes you have made and gives you
80 an opportunity to keep a nice record of what you have done. This looks like
81 this::
82
83 $ ...do work in ipython-mybranch...
84 $ bzr commit -m "the commit message goes here"
85
86 Please note that since we now don't use an old-style linear ChangeLog (that
87 tends to cause problems with distributed version control systems), you should
88 ensure that your log messages are reasonably detailed. Use a docstring-like
89 approach in the commit messages (including the second line being left
90 *blank*)::
91
92 Single line summary of changes being committed.
93
94 * more details when warranted ...
95 * including crediting outside contributors if they sent the
96 code/bug/idea!
97
98 As you work, you will repeat this edit/commit cycle many times. If you work on
99 your branch for a long time, you will also want to get the latest changes from
100 the :file:`lp:ipython` branch. This can be done with the following sequence of
101 commands::
102
103 $ ls
104 ipython
105 ipython-mybranch
106
107 $ cd ipython
108 $ bzr pull
109 $ cd ../ipython-mybranch
110 $ bzr merge ../ipython
111 $ bzr commit -m "Merging changes from trunk"
112
113 Along the way, you should also run the IPython test suite. You can do this
114 using the :command:`iptest` command (which is basically a customized version of
115 :command:`nosetests`)::
116
117 $ cd
118 $ iptest
119
120 The :command:`iptest` command will also pick up and run any tests you have
121 written. See :ref:`testing documentation <devel_testing>` for further details
122 on the testing system.
123
124
125 Post your branch and request a code review
126 ------------------------------------------
127
128 Once you are done with your edits, you should post your branch on Launchpad so
129 that other IPython developers can review the changes and help you merge your
130 changes into the main development branch. To post your branch on Launchpad,
131 do::
132
133 $ cd ipython-mybranch
134 $ bzr push lp:~yourusername/ipython/ipython-mybranch
135
136 Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
137 should see your branch under the "Code" tab. If you click on your branch, you
138 can provide a short description of the branch as well as mark its status. Most
139 importantly, you should click the link that reads "Propose for merging into
140 another branch". What does this do?
141
142 This let's the other IPython developers know that your branch is ready to be
143 reviewed and merged into the main development branch. During this review
144 process, other developers will give you feedback and help you get your code
145 ready to be merged. What types of things will we be looking for:
146
147 * All code is documented.
148 * All code has tests.
149 * The entire IPython test suite passes.
150
151 Once your changes have been reviewed and approved, someone will merge them
152 into the main development branch.
153
154
155 Some notes for core developers when merging third-party contributions
156 =====================================================================
157
158 Core developers, who ultimately merge any approved branch (from themselves,
159 another developer, or any third-party contribution) will typically use
160 :command:`bzr merge` to merge the branch into the trunk and push it to the
161 main Launcphad site. This is a short list of things to keep in mind when doing
162 this process, so that the project history is easy to understand in the long
163 run, and that generating release notes is as painless and accurate as
164 possible.
165
166 - When you merge any non-trivial functionality (from one small bug fix to a
167 big feature branch), please remember to always edit the :file:`changes.txt`
168 file accordingly. This file has one main section for each release, and if
169 you edit it as you go, noting what new features, bug fixes or API changes
170 you have made, the release notes will be almost finished when they are
171 needed later. This is much easier if done when you merge the work, rather
172 than weeks or months later by re-reading a massive Bazaar log.
173
174 - When big merges are done, the practice of putting a summary commit message
175 in the merge is *extremely* useful. It makes this kind of job much nicer,
176 because that summary log message can be almost copy/pasted without changes,
177 if it was well written, rather than dissecting the next-level messages from
178 the individual commits.
179
180 - It's important that we remember to always credit who gave us something if
181 it's not the committer. In general, we have been fairly good on this front,
182 this is just a reminder to keep things up. As a note, if you are ever
183 committing something that is completely (or almost so) a third-party
184 contribution, do the commit as::
185
186 $ bzr commit --author="Someone Else"
187
188 This way it will show that name separately in the log, which makes it even
189 easier to spot. Obviously we often rework third party contributions
190 extensively, but this is still good to keep in mind for cases when we don't
191 touch the code too much. No newline at end of file
@@ -0,0 +1,25 b''
1 Release checklist
2 =================
3
4 Most of the release process is automated by the :file:`release` script in the
5 :file:`tools` directory. This is just a handy reminder for the release manager.
6
7 #. First, run :file:`build_release`, which does all the file checking and
8 building that the real release script will do. This will let you do test
9 installations, check that the build procedure runs OK, etc. You may want to
10 disable a few things like multi-version RPM building while testing, because
11 otherwise the build takes really long.
12
13 #. Run the release script, which makes the tar.gz, eggs and Win32 .exe
14 installer. It posts them to the site and registers the release with PyPI.
15
16 #. Updating the website with announcements and links to the updated
17 changes.txt in html form. Remember to put a short note both on the news
18 page of the site and on Launcphad.
19
20 #. Drafting a short release announcement with i) highlights and ii) a link to
21 the html changes.txt.
22
23 #. Make sure that the released version of the docs is live on the site.
24
25 #. Celebrate! No newline at end of file
@@ -0,0 +1,194 b''
1 .. _testing:
2
3 =========================
4 Writing and running tests
5 =========================
6
7 Overview
8 ========
9
10 It is extremely important that all code contributed to IPython has tests.
11 Tests should be written as unittests, doctests or other entities that the
12 IPython test system can detect. See below for more details on this.
13
14 Each subpackage in IPython should have its own :file:`tests` directory that
15 contains all of the tests for that subpackage. All of the files in the
16 :file:`tests` directory should have the word "tests" in them to enable
17 the testing framework to find them.
18
19 If a subpackage has any dependencies beyond the Python standard library, the
20 tests for that subpackage should be skipped if the dependencies are not found.
21 This is very important so users don't get tests failing simply because they
22 don't have dependencies. We are still figuring out the best way for this
23 to be handled.
24
25 Status
26 ======
27
28 Currently IPython's testing system is being reworked. In the meantime,
29 we recommend the following testing practices:
30
31 * To run regular tests, use the :cmd:`nosetests` command on a per file basis:
32
33 .. code-block:: bash
34
35 nosetests -vvs IPython.core.tests.test_component
36
37 * To run Twisted-using tests, use the :cmd:`trial` command on a per file
38 basis:
39
40 .. code-block:: bash
41
42 trial IPython.kernel
43
44 * For now, regular tests (of non-Twisted using code) should be written as
45 unit tests. They should be subclasses of :class:`unittest.TestCase`.
46
47 * Tests of Twisted [Twisted]_ using code should be written by subclassing the
48 ``TestCase`` class that comes with ``twisted.trial.unittest``.
49
50 .. _devel_testing:
51
52 Older material
53 ==============
54
55 It is extremely important that all code contributed to IPython has tests.
56 Tests should be written as unittests, doctests or as entities that the Nose
57 [Nose]_ testing package will find. Regardless of how the tests are written, we
58 will use Nose for discovering and running the tests. Nose will be required to
59 run the IPython test suite, but will not be required to simply use IPython.
60
61 Tests of Twisted using code need to follow two additional guidelines:
62
63 1. Twisted using tests should be written by subclassing the :class:`TestCase`
64 class that comes with :mod:`twisted.trial.unittest`.
65
66 2. All :class:`Deferred` instances that are created in the test must be
67 properly chained and the final one *must* be the return value of the test
68 method.
69
70 When these two things are done, Nose will be able to run the tests and the
71 twisted reactor will be handled correctly.
72
73 Each subpackage in IPython should have its own :file:`tests` directory that
74 contains all of the tests for that subpackage. This allows each subpackage to
75 be self-contained. A good convention to follow is to have a file named
76 :file:`test_foo.py` for each module :file:`foo.py` in the package. This makes
77 it easy to organize the tests, though like most conventions, it's OK to break
78 it if logic and common sense dictate otherwise.
79
80 If a subpackage has any dependencies beyond the Python standard library, the
81 tests for that subpackage should be skipped if the dependencies are not
82 found. This is very important so users don't get tests failing simply because
83 they don't have dependencies. We ship a set of decorators in the
84 :mod:`IPython.testing` package to tag tests that may be platform-specific or
85 otherwise may have restrictions; if the existing ones don't fit your needs, add
86 a new decorator in that location so other tests can reuse it.
87
88 To run the IPython test suite, use the :command:`iptest` command that is
89 installed with IPython (if you are using IPython in-place, without installing
90 it, you can find this script in the :file:`scripts` directory)::
91
92 $ iptest
93
94 This command colects all IPython tests into separate groups, and then calls
95 either Nose with the proper options and extensions, or Twisted's
96 :command:`trial`. This ensures that tests that need the Twisted reactor
97 management facilities execute separate of Nose. If any individual test group
98 fails, :command:`iptest` will print what you need to type so you can rerun that
99 particular test group alone for debugging.
100
101 By default, :command:`iptest` runs the entire IPython test
102 suite (skipping tests that may be platform-specific or which depend on tools
103 you may not have). But you can also use it to run only one specific test file,
104 or a specific test function. For example, this will run only the
105 :file:`test_magic` file from the test suite::
106
107 $ iptest IPython.tests.test_magic
108 ----------------------------------------------------------------------
109 Ran 10 tests in 0.348s
110
111 OK (SKIP=3)
112 Deleting object: second_pass
113
114 while the ``path:function`` syntax allows you to select a specific function in
115 that file to run::
116
117 $ iptest IPython.tests.test_magic:test_obj_del
118 ----------------------------------------------------------------------
119 Ran 1 test in 0.204s
120
121 OK
122
123 Since :command:`iptest` is based on nosetests, you can pass it any regular
124 nosetests option. For example, you can use ``--pdb`` or ``--pdb-failures`` to
125 automatically activate the interactive Pdb debugger on errors or failures. See
126 the nosetests documentation for further details.
127
128
129 A few tips for writing tests
130 ----------------------------
131
132 You can write tests either as normal test files, using all the conventions that
133 Nose recognizes, or as doctests. Note that *all* IPython functions should have
134 at least one example that serves as a doctest, whenever technically feasible.
135 However, example doctests should only be in the main docstring if they are *a
136 good example*, i.e. if they convey useful information about the function. If
137 you simply would like to write a test as a doctest, put it in a separate test
138 file and write a no-op function whose only purpose is its docstring.
139
140 Note, however, that in a file named :file:`test_X`, functions whose only test
141 is their docstring (as a doctest) and which have no test functionality of their
142 own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
143 double-counted (the empty function call is counted as a test, which just
144 inflates tests numbers artificially). This restriction does not apply to
145 functions in files with other names, due to how Nose discovers tests.
146
147 You can use IPython examples in your docstrings. Those can make full use of
148 IPython functionality (magics, variable substitution, etc), but be careful to
149 keep them generic enough that they run identically on all Operating Systems.
150
151 The prompts in your doctests can be either of the plain Python ``>>>`` variety
152 or ``In [1]:`` IPython style. Since this is the IPython system, after all, we
153 encourage you to use IPython prompts throughout, unless you are illustrating a
154 specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
155
156 If a test isn't safe to run inside the main nose process (e.g. because it loads
157 a GUI toolkit), consider running it in a subprocess and capturing its output
158 for evaluation and test decision later. Here is an example of how to do it, by
159 relying on the builtin ``_ip`` object that contains the public IPython api as
160 defined in :mod:`IPython.ipapi`::
161
162 def test_obj_del():
163 """Test that object's __del__ methods are called on exit."""
164 test_dir = os.path.dirname(__file__)
165 del_file = os.path.join(test_dir,'obj_del.py')
166 out = _ip.IP.getoutput('ipython %s' % del_file)
167 nt.assert_equals(out,'object A deleted')
168
169
170
171 If a doctest contains input whose output you don't want to verify identically
172 via doctest (random output, an object id, etc), you can mark a docstring with
173 ``#random``. All of these test will have their code executed but no output
174 checking will be done::
175
176 >>> 1+3
177 junk goes here... # random
178
179 >>> 1+2
180 again, anything goes #random
181 if multiline, the random mark is only needed once.
182
183 >>> 1+2
184 You can also put the random marker at the end:
185 # random
186
187 >>> 1+2
188 # random
189 .. or at the beginning.
190
191 In a case where you want an *entire* docstring to be executed but not verified
192 (this only serves to check that the code runs without crashing, so it should be
193 used very sparingly), you can put ``# all-random`` in the docstring.
194
@@ -1,208 +1,209 b''
1 1 .. _credits:
2 2
3 3 =======
4 4 Credits
5 5 =======
6 6
7 IPython is led by Fernando Pérez.
7 IPython was started and continues to be led by Fernando Pérez.
8 8
9 As of this writing, the following developers have joined the core team:
9 Core developers
10 ===============
10 11
11 * [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
12 Google Summer of Code project to develop python interactive
13 notebooks (XML documents) and graphical interface. This project
14 was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
15 Toni Alatalo <antont-AT-an.org>.
12 As of this writing, core development team consists of the following
13 developers:
16 14
17 * [Brian Granger] <ellisonbg-AT-gmail.com>: extending IPython to allow
18 support for interactive parallel computing.
15 * **Fernando Pérez** <Fernando.Perez-AT-berkeley.edu> Project creator and leader,
16 IPython core, parallel computing infrastructure, testing, release manager.
19 17
20 * [Benjamin (Min) Ragan-Kelley]: key work on IPython's parallel
21 computing infrastructure.
18 * **Robert Kern** <rkern-AT-enthought.com> Co-mentored the 2005 Google Summer of
19 Code project, work on IPython's core.
22 20
23 * [Ville Vainio] <vivainio-AT-gmail.com>: Ville has made many improvements
24 to the core of IPython and was the maintainer of the main IPython
25 trunk from version 0.7.1 to 0.8.4.
21 * **Brian Granger** <ellisonbg-AT-gmail.com> Parallel computing
22 infrastructure, IPython core.
26 23
27 * [Gael Varoquaux] <gael.varoquaux-AT-normalesup.org>: work on the merged
28 architecture for the interpreter as of version 0.9, implementing a new WX GUI
29 based on this system.
24 * **Benjamin (Min) Ragan-Kelley** <benjaminrk-AT-gmail.com> Parallel computing
25 infrastructure.
30 26
31 * [Barry Wark] <barrywark-AT-gmail.com>: implementing a new Cocoa GUI, as well
32 as work on the new interpreter architecture and Twisted support.
27 * **Ville Vainio** <vivainio-AT-gmail.com> IPython core, maintainer of IPython
28 trunk from version 0.7.2 to 0.8.4.
33 29
34 * [Laurent Dufrechou] <laurent.dufrechou-AT-gmail.com>: development of the WX
35 GUI support.
30 * **Gael Varoquaux** <gael.varoquaux-AT-normalesup.org> wxPython IPython GUI,
31 frontend architecture.
36 32
37 * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu>: maintainer of the
38 PyReadline project, necessary for IPython under windows.
33 * **Barry Wark** <barrywark-AT-gmail.com> Cocoa GUI, frontend architecture.
39 34
35 * **Laurent Dufrechou** <laurent.dufrechou-AT-gmail.com> wxPython IPython GUI.
36
37 * **Jörgen Stenarson** <jorgen.stenarson-AT-bostream.nu> Maintainer of the
38 PyReadline project, which is needed for IPython under windows.
39
40 Special thanks
41 ==============
40 42
41 43 The IPython project is also very grateful to:
42 44
43 Bill Bumgarner <bbum-AT-friday.com>: for providing the DPyGetOpt module
44 which gives very powerful and convenient handling of command-line
45 options (light years ahead of what Python 2.1.1's getopt module does).
45 Bill Bumgarner <bbum-AT-friday.com>, for providing the DPyGetOpt module that
46 IPython used for parsing command line options through version 0.10.
46 47
47 Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for
48 convenient and powerful string interpolation with a much nicer syntax
49 than formatting through the '%' operator.
48 Ka-Ping Yee <ping-AT-lfw.org>, for providing the Itpl module for convenient
49 and powerful string interpolation with a much nicer syntax than formatting
50 through the '%' operator.
50 51
51 Arnd Baecker <baecker-AT-physik.tu-dresden.de>: for his many very useful
52 suggestions and comments, and lots of help with testing and
53 documentation checking. Many of IPython's newer features are a result of
54 discussions with him (bugs are still my fault, not his).
52 Arnd Baecker <baecker-AT-physik.tu-dresden.de>, for his many very useful
53 suggestions and comments, and lots of help with testing and documentation
54 checking. Many of IPython's newer features are a result of discussions with
55 him.
55 56
56 Obviously Guido van Rossum and the whole Python development team, that
57 goes without saying.
57 Obviously Guido van Rossum and the whole Python development team, for creating
58 a great language for interactive computing.
58 59
59 IPython's website is generously hosted at http://ipython.scipy.orgby
60 Enthought (http://www.enthought.com). I am very grateful to them and all
61 of the SciPy team for their contribution.
60 Enthought (http://www.enthought.com), for hosting IPython's website and
61 supporting the project in various ways over the years.
62 62
63 63 Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>,
64 an O'Reilly Python editor. His Oct/11/2001 article about IPP and
65 LazyPython, was what got this project started. You can read it at:
64 an O'Reilly Python editor. His October 11, 2001 article about IPP and
65 LazyPython, was what got this project started. You can read it at
66 66 http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html.
67 67
68 And last but not least, all the kind IPython users who have emailed new code,
69 bug reports, fixes, comments and ideas. A brief list follows, please let us
70 know if we have ommitted your name by accident:
68 Contributors
69 ============
70
71 And last but not least, all the kind IPython contributors who have contributed
72 new code, bug reports, fixes, comments and ideas. A brief list follows, please
73 let us know if we have omitted your name by accident:
71 74
72 * Dan Milstein <danmil-AT-comcast.net>. A bold refactoring of the
73 core prefilter stuff in the IPython interpreter.
75 * Dan Milstein <danmil-AT-comcast.net> A bold refactor of the core prefilter
76 machinery in the IPython interpreter.
74 77
75 * [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
76 color problem. This bug alone caused many lost hours and
77 frustration, many thanks to him for the fix. I've always been a
78 fan of Ogg & friends, now I have one more reason to like these folks.
79 Jack is also contributing with Debian packaging and many other
80 things.
78 * Jack Moffit <jack-AT-xiph.org> Bug fixes, including the infamous color
79 problem. This bug alone caused many lost hours and frustration, many thanks
80 to him for the fix. I've always been a fan of Ogg & friends, now I have one
81 more reason to like these folks. Jack is also contributing with Debian
82 packaging and many other things.
81 83
82 * [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug
83 reports, bug fixes, ideas, lots more. The ipython.el mode for
84 (X)Emacs is Alex's code, providing full support for IPython under
85 (X)Emacs.
84 * Alexander Schmolck <a.schmolck-AT-gmx.net> Emacs work, bug reports, bug
85 fixes, ideas, lots more. The ipython.el mode for (X)Emacs is Alex's code,
86 providing full support for IPython under (X)Emacs.
86 87
87 * [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
88 information, Fink package management.
88 * Andrea Riciputi <andrea.riciputi-AT-libero.it> Mac OSX information, Fink
89 package management.
89 90
90 * [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
91 around the exception handling idiosyncracies of WxPython. Readline
92 and color support for Windows.
91 * Gary Bishop <gb-AT-cs.unc.edu> Bug reports, and patches to work around the
92 exception handling idiosyncracies of WxPython. Readline and color support
93 for Windows.
93 94
94 * [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
95 improved readline support, including fixes for Python 2.3.
95 * Jeffrey Collins <Jeff.Collins-AT-vexcel.com>. Bug reports. Much improved
96 readline support, including fixes for Python 2.3.
96 97
97 * [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
98 * Dryice Liu <dryice-AT-liu.com.cn> FreeBSD port.
98 99
99 * [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
100 * Mike Heeter <korora-AT-SDF.LONESTAR.ORG>
100 101
101 * [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
102 * Christopher Hart <hart-AT-caltech.edu> PDB integration.
102 103
103 * [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
104 * Milan Zamazal <pdm-AT-zamazal.org> Emacs info.
104 105
105 * [Philip Hisley] <compsys-AT-starpower.net>
106 * Philip Hisley <compsys-AT-starpower.net>
106 107
107 * [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
108 more.
108 * Holger Krekel <pyth-AT-devel.trillke.net> Tab completion, lots more.
109 109
110 * [Robin Siebler] <robinsiebler-AT-starband.net>
110 * Robin Siebler <robinsiebler-AT-starband.net>
111 111
112 * [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
112 * Ralf Ahlbrink <ralf_ahlbrink-AT-web.de>
113 113
114 * [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
114 * Thorsten Kampe <thorsten-AT-thorstenkampe.de>
115 115
116 * [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
116 * Fredrik Kant <fredrik.kant-AT-front.com> Windows setup.
117 117
118 * [Syver Enstad] <syver-en-AT-online.no> Windows setup.
118 * Syver Enstad <syver-en-AT-online.no> Windows setup.
119 119
120 * [Richard] <rxe-AT-renre-europe.com> Global embedding.
120 * Richard <rxe-AT-renre-europe.com> Global embedding.
121 121
122 * [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
122 * Hayden Callow <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
123 123 compatibility.
124 124
125 * [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
125 * Leonardo Santagada <retype-AT-terra.com.br> Fixes for Windows
126 126 installation.
127 127
128 * [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
128 * Christopher Armstrong <radix-AT-twistedmatrix.com> Bugfixes.
129 129
130 * [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
130 * Francois Pinard <pinard-AT-iro.umontreal.ca> Code and
131 131 documentation fixes.
132 132
133 * [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
133 * Cory Dodt <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
134 134 ideas. Patches for Windows installer.
135 135
136 * [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
136 * Olivier Aubert <oaubert-AT-bat710.univ-lyon1.fr> New magics.
137 137
138 * [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
138 * King C. Shu <kingshu-AT-myrealbox.com> Autoindent patch.
139 139
140 * [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
140 * Chris Drexler <chris-AT-ac-drexler.de> Readline packages for
141 141 Win32/CygWin.
142 142
143 * [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
143 * Gustavo Cordova Avila <gcordova-AT-sismex.com> EvalDict code for
144 144 nice, lightweight string interpolation.
145 145
146 * [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
146 * Kasper Souren <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
147 147
148 * [Gever Tulley] <gever-AT-helium.com> Code contributions.
148 * Gever Tulley <gever-AT-helium.com> Code contributions.
149 149
150 * [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
150 * Ralf Schmitt <ralf-AT-brainbot.com> Bug reports & fixes.
151 151
152 * [Oliver Sander] <osander-AT-gmx.de> Bug reports.
152 * Oliver Sander <osander-AT-gmx.de> Bug reports.
153 153
154 * [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
154 * Rod Holland <rhh-AT-structurelabs.com> Bug reports and fixes to
155 155 logging module.
156 156
157 * [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
157 * Daniel 'Dang' Griffith <pythondev-dang-AT-lazytwinacres.net>
158 158 Fixes, enhancement suggestions for system shell use.
159 159
160 * [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
160 * Viktor Ransmayr <viktor.ransmayr-AT-t-online.de> Tests and
161 161 reports on Windows installation issues. Contributed a true Windows
162 162 binary installer.
163 163
164 * [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
164 * Mike Salib <msalib-AT-mit.edu> Help fixing a subtle bug related
165 165 to traceback printing.
166 166
167 * [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
167 * W.J. van der Laan <gnufnork-AT-hetdigitalegat.nl> Bash-like
168 168 prompt specials.
169 169
170 * [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
170 * Antoon Pardon <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
171 171 the multithreaded IPython.
172 172
173 * [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
173 * John Hunter <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
174 174 author, helped with all the development of support for matplotlib
175 175 in IPyhton, including making necessary changes to matplotlib itself.
176 176
177 * [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
177 * Matthew Arnison <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
178 178
179 * [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
179 * Prabhu Ramachandran <prabhu_r-AT-users.sourceforge.net> Help
180 180 with (X)Emacs support, threading patches, ideas...
181 181
182 * [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
182 * Norbert Tretkowski <tretkowski-AT-inittab.de> help with Debian
183 183 packaging and distribution.
184 184
185 * [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
185 * George Sakkis <gsakkis-AT-eden.rutgers.edu> New matcher for
186 186 tab-completing named arguments of user-defined functions.
187 187
188 * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
188 * Jörgen Stenarson <jorgen.stenarson-AT-bostream.nu> Wildcard
189 189 support implementation for searching namespaces.
190 190
191 * [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
191 * Vivian De Smedt <vivian-AT-vdesmedt.com> Debugger enhancements,
192 192 so that when pdb is activated from within IPython, coloring, tab
193 193 completion and other features continue to work seamlessly.
194 194
195 * [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
195 * Scott Tsai <scottt958-AT-yahoo.com.tw> Support for automatic
196 196 editor invocation on syntax errors (see
197 197 http://www.scipy.net/roundup/ipython/issue36).
198 198
199 * [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
199 * Alexander Belchenko <bialix-AT-ukr.net> Improvements for win32
200 200 paging system.
201 201
202 * [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
202 * Will Maier <willmaier-AT-ml1.net> Official OpenBSD port.
203 203
204 * [Ondrej Certik] <ondrej-AT-certik.cz>: set up the IPython docs to use the new
204 * Ondrej Certik <ondrej-AT-certik.cz> Set up the IPython docs to use the new
205 205 Sphinx system used by Python, Matplotlib and many more projects.
206 206
207 * [Stefan van der Walt] <stefan-AT-sun.ac.za>: support for the new config system.
207 * Stefan van der Walt <stefan-AT-sun.ac.za> Design and prototype of the
208 Traits based config system.
208 209
@@ -1,38 +1,34 b''
1 1 .. _history:
2 2
3 3 =======
4 4 History
5 5 =======
6 6
7 7 Origins
8 8 =======
9 9
10 IPython was starting in 2001 by Fernando Perez. IPython as we know it
11 today grew out of the following three projects:
12
13 * ipython by Fernando Pérez. I was working on adding
14 Mathematica-type prompts and a flexible configuration system
15 (something better than $PYTHONSTARTUP) to the standard Python
16 interactive interpreter.
10 IPython was starting in 2001 by Fernando Perez while he was a graduate student
11 at the University of Colorado, Boulder. IPython as we know it today grew out
12 of the following three projects:
13
14 * ipython by Fernando Pérez. Fernando began using Python and ipython began as
15 an outgrowth of his desire for things like Mathematica-style prompts, access
16 to previous output (again like Mathematica's % syntax) and a flexible
17 configuration system (something better than :envvar:`PYTHONSTARTUP`).
17 18 * IPP by Janko Hauser. Very well organized, great usability. Had
18 an old help system. IPP was used as the 'container' code into
19 which I added the functionality from ipython and LazyPython.
19 an old help system. IPP was used as the "container" code into
20 which Fernando added the functionality from ipython and LazyPython.
20 21 * LazyPython by Nathan Gray. Simple but very powerful. The quick
21 22 syntax (auto parens, auto quotes) and verbose/colored tracebacks
22 23 were all taken from here.
23 24
24 Here is how Fernando describes it:
25 Here is how Fernando describes the early history of IPython:
25 26
26 27 When I found out about IPP and LazyPython I tried to join all three
27 28 into a unified system. I thought this could provide a very nice
28 29 working environment, both for regular programming and scientific
29 30 computing: shell-like features, IDL/Matlab numerics, Mathematica-type
30 31 prompt history and great object introspection and help facilities. I
31 32 think it worked reasonably well, though it was a lot more work than I
32 33 had initially planned.
33 34
34 Today and how we got here
35 =========================
36
37 This needs to be filled in.
38
@@ -1,92 +1,95 b''
1 1 .. _license:
2 2
3 3 =====================
4 4 License and Copyright
5 5 =====================
6 6
7 7 License
8 8 =======
9 9
10 IPython is licensed under the terms of the new or revised BSD license, as follows::
10 IPython is licensed under the terms of the new or revised BSD license, as
11 follows::
11 12
12 13 Copyright (c) 2008, IPython Development Team
13 14
14 15 All rights reserved.
15 16
16 17 Redistribution and use in source and binary forms, with or without
17 18 modification, are permitted provided that the following conditions are
18 19 met:
19 20
20 21 Redistributions of source code must retain the above copyright notice,
21 22 this list of conditions and the following disclaimer.
22 23
23 24 Redistributions in binary form must reproduce the above copyright notice,
24 25 this list of conditions and the following disclaimer in the documentation
25 26 and/or other materials provided with the distribution.
26 27
27 28 Neither the name of the IPython Development Team nor the names of its
28 29 contributors may be used to endorse or promote products derived from this
29 30 software without specific prior written permission.
30 31
31 32 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
32 33 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
33 34 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
34 35 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
35 36 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
36 37 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
37 38 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
38 39 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
39 40 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
40 41 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
41 42 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 43
43 44 About the IPython Development Team
44 45 ==================================
45 46
46 47 Fernando Perez began IPython in 2001 based on code from Janko Hauser
47 <jhauser@zscout.de> and Nathaniel Gray <n8gray@caltech.edu>. Fernando is still
48 <jhauser-AT-zscout.de> and Nathaniel Gray <n8gray-AT-caltech.edu>. Fernando is still
48 49 the project lead.
49 50
50 51 The IPython Development Team is the set of all contributors to the IPython
51 52 project. This includes all of the IPython subprojects. Here is a list of the
52 53 currently active contributors:
53 54
54 * Matthieu Brucher
55 * Ondrej Certik
56 * Laurent Dufrechou
57 * Robert Kern
58 * Brian E. Granger
59 * Fernando Perez (project leader)
60 * Benjamin Ragan-Kelley
61 * Ville M. Vainio
62 * Gael Varoququx
63 * Stefan van der Walt
64 * Tech-X Corporation
65 * Barry Wark
55 * Matthieu Brucher
56 * Ondrej Certik
57 * Laurent Dufrechou
58 * Robert Kern
59 * Brian E. Granger
60 * Fernando Perez (project leader)
61 * Benjamin Ragan-Kelley
62 * Ville M. Vainio
63 * Gael Varoququx
64 * Stefan van der Walt
65 * Barry Wark
66 66
67 67 If your name is missing, please add it.
68 68
69 69 Our Copyright Policy
70 70 ====================
71 71
72 72 IPython uses a shared copyright model. Each contributor maintains copyright
73 73 over their contributions to IPython. But, it is important to note that these
74 contributions are typically only changes to the repositories. Thus, the
75 IPython source code, in its entirety is not the copyright of any single person
76 or institution. Instead, it is the collective copyright of the entire IPython
77 Development Team. If individual contributors want to maintain a record of what
78 changes/contributions they have specific copyright on, they should indicate
79 their copyright in the commit message of the change, when they commit the
80 change to one of the IPython repositories.
74 contributions are typically only changes (diffs/commits) to the repositories.
75 Thus, the IPython source code, in its entirety is not the copyright of any
76 single person or institution. Instead, it is the collective copyright of the
77 entire IPython Development Team. If individual contributors want to maintain a
78 record of what changes/contributions they have specific copyright on, they
79 should indicate their copyright in the commit message of the change, when they
80 commit the change to one of the IPython repositories.
81
82 Any new code contributed to IPython must be licensed under the BSD license or
83 a similar (MIT) open source license.
81 84
82 85 Miscellaneous
83 86 =============
84 87
85 88 Some files (DPyGetOpt.py, for example) may be licensed under different
86 89 conditions. Ultimately each file indicates clearly the conditions under which
87 90 its author/authors have decided to publish the code.
88 91
89 92 Versions of IPython up to and including 0.6.3 were released under the GNU
90 93 Lesser General Public License (LGPL), available at
91 94 http://www.gnu.org/copyleft/lesser.html.
92 95
@@ -1,142 +1,156 b''
1 1 ==============
2 2 Coding guide
3 3 ==============
4 4
5 5
6 6 Coding conventions
7 7 ==================
8 8
9 9 In general, we'll try to follow the standard Python style conventions as
10 10 described in Python's `PEP 8`_, the official Python Style Guide.
11 11
12 12 .. _PEP 8: http://www.python.org/peps/pep-0008.html
13 13
14 14 Other comments:
15 15
16 16 - In a large file, top level classes and functions should be separated by 2-3
17 17 lines to make it easier to separate them visually.
18 18
19 19 - Use 4 spaces for indentation, *never* use hard tabs.
20 20
21 21 - Keep the ordering of methods the same in classes that have the same methods.
22 22 This is particularly true for classes that implement similar interfaces and
23 23 for interfaces that are similar.
24 24
25 25 Naming conventions
26 26 ------------------
27 27
28 28 In terms of naming conventions, we'll follow the guidelines of PEP 8. Some of
29 29 the existing code doesn't honor this perfectly, but for all new IPython code
30 30 (and much existing code is being refactored), we'll use:
31 31
32 32 - All ``lowercase`` module names.
33 33
34 34 - ``CamelCase`` for class names.
35 35
36 36 - ``lowercase_with_underscores`` for methods, functions, variables and
37 37 attributes.
38 38
39 39 This may be confusing as some of the existing codebase uses a different
40 40 convention (``lowerCamelCase`` for methods and attributes). Slowly, we will
41 41 move IPython over to the new convention, providing shadow names for backward
42 42 compatibility in public interfaces.
43 43
44 44 There are, however, some important exceptions to these rules. In some cases,
45 45 IPython code will interface with packages (Twisted, Wx, Qt) that use other
46 46 conventions. At some level this makes it impossible to adhere to our own
47 47 standards at all times. In particular, when subclassing classes that use other
48 48 naming conventions, you must follow their naming conventions. To deal with
49 49 cases like this, we propose the following policy:
50 50
51 51 - If you are subclassing a class that uses different conventions, use its
52 52 naming conventions throughout your subclass. Thus, if you are creating a
53 53 Twisted Protocol class, used Twisted's
54 54 ``namingSchemeForMethodsAndAttributes.``
55 55
56 56 - All IPython's official interfaces should use our conventions. In some cases
57 57 this will mean that you need to provide shadow names (first implement
58 58 ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
59 59 costs, but it will probably be necessary at times. But, please use this
60 60 sparingly!
61 61
62 62 Implementation-specific *private* methods will use
63 63 ``_single_underscore_prefix``. Names with a leading double underscore will
64 64 *only* be used in special cases, as they makes subclassing difficult (such
65 65 names are not easily seen by child classes).
66 66
67 67 Occasionally some run-in lowercase names are used, but mostly for very short
68 68 names or where we are implementing methods very similar to existing ones in a
69 69 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
70 70 established precedent).
71 71
72 72 The old IPython codebase has a big mix of classes and modules prefixed with an
73 73 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
74 74 upon, as namespaces offer cleaner prefixing. The only case where this approach
75 75 is justified is for classes which are expected to be imported into external
76 76 namespaces and a very generic name (like Shell) is too likely to clash with
77 77 something else. We'll need to revisit this issue as we clean up and refactor
78 78 the code, but in general we should remove as many unnecessary ``IP``/``ip``
79 79 prefixes as possible. However, if a prefix seems absolutely necessary the more
80 80 specific ``IPY`` or ``ipy`` are preferred.
81 81
82 Older material
83 ==============
82 84
83 .. _devel-testing:
85 General
86 -------
84 87
85 Testing system
86 ==============
88 In general, we'll try to follow the standard Python style conventions as
89 described here:
90
91 * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
92
93
94 Other comments:
95
96 * In a large file, top level classes and functions should be
97 separated by 2-3 lines to make it easier to separate them visually.
98 * Use 4 spaces for indentation.
99 * Keep the ordering of methods the same in classes that have the same
100 methods. This is particularly true for classes that implement an interface.
101
102 Naming conventions
103 ------------------
104
105 In terms of naming conventions, we'll follow the guidelines from the `Style
106 Guide for Python Code`_.
107
108 For all new IPython code (and much existing code is being refactored), we'll
109 use:
110
111 * All ``lowercase`` module names.
112
113 * ``CamelCase`` for class names.
114
115 * ``lowercase_with_underscores`` for methods, functions, variables and
116 attributes.
117
118 There are, however, some important exceptions to these rules. In some cases,
119 IPython code will interface with packages (Twisted, Wx, Qt) that use other
120 conventions. At some level this makes it impossible to adhere to our own
121 standards at all times. In particular, when subclassing classes that use other
122 naming conventions, you must follow their naming conventions. To deal with
123 cases like this, we propose the following policy:
124
125 * If you are subclassing a class that uses different conventions, use its
126 naming conventions throughout your subclass. Thus, if you are creating a
127 Twisted Protocol class, used Twisted's
128 ``namingSchemeForMethodsAndAttributes.``
129
130 * All IPython's official interfaces should use our conventions. In some cases
131 this will mean that you need to provide shadow names (first implement
132 ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
133 costs, but it will probably be necessary at times. But, please use this
134 sparingly!
135
136 Implementation-specific *private* methods will use
137 ``_single_underscore_prefix``. Names with a leading double underscore will
138 *only* be used in special cases, as they makes subclassing difficult (such
139 names are not easily seen by child classes).
140
141 Occasionally some run-in lowercase names are used, but mostly for very short
142 names or where we are implementing methods very similar to existing ones in a
143 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
144 established precedent).
145
146 The old IPython codebase has a big mix of classes and modules prefixed with an
147 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
148 upon, as namespaces offer cleaner prefixing. The only case where this approach
149 is justified is for classes which are expected to be imported into external
150 namespaces and a very generic name (like Shell) is too likely to clash with
151 something else. We'll need to revisit this issue as we clean up and refactor
152 the code, but in general we should remove as many unnecessary ``IP``/``ip``
153 prefixes as possible. However, if a prefix seems absolutely necessary the more
154 specific ``IPY`` or ``ipy`` are preferred.
87 155
88 It is extremely important that all code contributed to IPython has tests. Tests
89 should be written as unittests, doctests or as entities that the `Nose`_
90 testing package will find. Regardless of how the tests are written, we will use
91 `Nose`_ for discovering and running the tests. `Nose`_ will be required to run
92 the IPython test suite, but will not be required to simply use IPython.
93
94 .. _Nose: http://code.google.com/p/python-nose/
95
96 Tests of `Twisted`__ using code should be written by subclassing the
97 ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
98 done, `Nose`_ will be able to run the tests and the twisted reactor will be
99 handled correctly.
100
101 .. __: http://www.twistedmatrix.com
102
103 Each subpackage in IPython should have its own ``tests`` directory that
104 contains all of the tests for that subpackage. This allows each subpackage to
105 be self-contained. If a subpackage has any dependencies beyond the Python
106 standard library, the tests for that subpackage should be skipped if the
107 dependencies are not found. This is very important so users don't get tests
108 failing simply because they don't have dependencies.
109
110 We also need to look into use Noses ability to tag tests to allow a more
111 modular approach of running tests.
112
113 .. _devel-config:
114
115 Configuration system
116 ====================
117
118 IPython uses `.ini`_ files for configuration purposes. This represents a huge
119 improvement over the configuration system used in IPython. IPython works with
120 these files using the `ConfigObj`_ package, which IPython includes as
121 ``ipython1/external/configobj.py``.
122
123 Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
124 IPython should contain a ``config`` subdirectory that contains all of the
125 configuration information for the subpackage. To see how configuration
126 information is defined (along with defaults) see at the examples in
127 ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
128 the configuration information is used, see examples in
129 ``ipython1/kernel/scripts/ipengine.py``.
130
131 Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
132 are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
133 validation model. We won't actually use `Traits`_, but will implement
134 something similar in pure Python. But, even in this new system, we will still
135 use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
136 are interested in working on this part of IPython. The current prototype of
137 ``tconfig`` is located in the IPython sandbox.
138
139 .. _.ini: http://docs.python.org/lib/module-ConfigParser.html
140 .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
141 .. _Traits: http://code.enthought.com/traits/
142 156
@@ -1,104 +1,141 b''
1 1 .. _documenting-ipython:
2 2
3 3 =====================
4 4 Documenting IPython
5 5 =====================
6 6
7 7 Standalone documentation
8 8 ========================
9 9
10 10 All standalone documentation should be written in plain text (``.txt``) files
11 11 using `reStructuredText`_ for markup and formatting. All such documentation
12 12 should be placed in the top level directory ``docs`` of the IPython source
13 13 tree. Or, when appropriate, a suitably named subdirectory should be used. The
14 14 documentation in this location will serve as the main source for IPython
15 15 documentation and all existing documentation should be converted to this
16 16 format.
17 17
18 18 The actual HTML and PDF docs are built using the Sphinx_ documentation
19 19 generation tool. Sphinx has been adopted as the default documentation tool for
20 20 Python itself as of version 2.6, as well as by a number of projects that
21 21 IPython is related with, such as numpy, scipy, matplotlib, sage and nipy.
22 22
23 23 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
24 24 .. _Sphinx: http://sphinx.pocoo.org/
25 25
26 26
27 27 The rest of this document is mostly taken from the `matploblib
28 28 documentation`__; we are using a number of Sphinx tools and extensions written
29 29 by the matplotlib team and will mostly follow their conventions, which are
30 30 nicely spelled out in their guide. What follows is thus a lightly adapted
31 31 version of the matplotlib documentation guide, taken with permission from the
32 32 MPL team.
33 33
34 34 .. __: http://matplotlib.sourceforge.net/devel/documenting_mpl.html
35 35
36 36
37 37 A bit of Python code::
38 38
39 39 for i in range(10):
40 40 print i,
41 41 print "A big number:",2**34
42 42
43 43 An interactive Python session::
44 44
45 45 >>> from IPython import genutils
46 46 >>> genutils.get_ipython_dir()
47 47 '/home/fperez/.ipython'
48 48
49 49
50 50 An IPython session:
51 51
52 52 .. code-block:: ipython
53 53
54 54 In [7]: import IPython
55 55
56 56 In [8]: print "This IPython is version:",IPython.__version__
57 57 This IPython is version: 0.9.1
58 58
59 59 In [9]: 2+4
60 60 Out[9]: 6
61 61
62 62
63 63 A bit of shell code:
64 64
65 65 .. code-block:: bash
66 66
67 67 cd /tmp
68 68 echo "My home directory is: $HOME"
69 69 ls
70 70
71 71
72 72 Docstring format
73 73 ================
74 74
75 75 Good docstrings are very important. Unfortunately, Python itself only provides
76 76 a rather loose standard for docstrings (`PEP 257`_), and there is no universally
77 77 accepted convention for all the different parts of a complete docstring.
78 78 However, the NumPy project has established a very reasonable standard, and has
79 79 developed some tools to support the smooth inclusion of such docstrings in
80 80 Sphinx-generated manuals. Rather than inventing yet another pseudo-standard,
81 81 IPython will be henceforth documented using the NumPy conventions; we carry
82 82 copies of some of the NumPy support tools to remain self-contained, but share
83 83 back upstream with NumPy any improvements or fixes we may make to the tools.
84 84
85 85 The `NumPy documentation guidelines`_ contain detailed information on this
86 86 standard, and for a quick overview, the NumPy `example docstring`_ is a useful
87 87 read.
88 88
89 89 As in the past IPython used epydoc, currently many docstrings still use epydoc
90 90 conventions. We will update them as we go, but all new code should be fully
91 91 documented using the NumPy standard.
92 92
93 93 .. _PEP 257: http://www.python.org/peps/pep-0257.html
94 94 .. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
95 95
96 96 .. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt
97 97
98 98 Additional PEPs of interest regarding documentation of code. While both of
99 99 these were rejected, the ideas therein form much of the basis of docutils (the
100 100 machinery to process reStructuredText):
101 101
102 102 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
103 103 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
104 104
105 Older material
106 ==============
107
108 Documentation
109 =============
110
111 Standalone documentation
112 ------------------------
113
114 All standalone documentation should be written in plain text (``.txt``) files
115 using reStructuredText [reStructuredText]_ for markup and formatting. All such
116 documentation should be placed in directory :file:`docs/source` of the IPython
117 source tree. The documentation in this location will serve as the main source
118 for IPython documentation and all existing documentation should be converted
119 to this format.
120
121 To build the final documentation, we use Sphinx [Sphinx]_. Once you have
122 Sphinx installed, you can build the html docs yourself by doing::
123
124 $ cd ipython-mybranch/docs
125 $ make html
126
127 Docstring format
128 ----------------
129
130 Good docstrings are very important. All new code should have docstrings that
131 are formatted using reStructuredText for markup and formatting, since it is
132 understood by a wide variety of tools. Details about using reStructuredText
133 for docstrings can be found `here
134 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
135
136 Additional PEPs of interest regarding documentation of code:
137
138 * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
139 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
140 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
141
@@ -1,16 +1,25 b''
1 ===========================
2 IPython Developer's Guide
3 ===========================
1 .. _developer_guide:
2
3 =========================
4 IPython developer's guide
5 =========================
4 6
5 7 .. toctree::
6 8 :maxdepth: 2
7 9
8 overview.txt
10 contributing.txt
9 11 coding_guide.txt
10 12 doc_guide.txt
13 testing.txt
14 release.txt
11 15 roadmap.txt
12 16
13 17 notification_blueprint.txt
14 config_blueprint.txt
15 18 reorg.txt
16 19
20
21 .. [Bazaar] Bazaar. http://bazaar-vcs.org/
22 .. [Launchpad] Launchpad. http://www.launchpad.net/ipython
23 .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html
24 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
25 .. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ No newline at end of file
@@ -1,108 +1,123 b''
1 1 .. _notification:
2 2
3 3 ==========================================
4 4 IPython.kernel.core.notification blueprint
5 5 ==========================================
6 6
7 7 Overview
8 8 ========
9 9
10 10 The :mod:`IPython.kernel.core.notification` module will provide a simple
11 11 implementation of a notification center and support for the observer pattern
12 12 within the :mod:`IPython.kernel.core`. The main intended use case is to
13 13 provide notification of Interpreter events to an observing frontend during the
14 14 execution of a single block of code.
15 15
16 16 Functional Requirements
17 17 =======================
18 18
19 19 The notification center must:
20 20
21 21 * Provide synchronous notification of events to all registered observers.
22 22
23 23 * Provide typed or labeled notification types.
24 24
25 25 * Allow observers to register callbacks for individual or all notification
26 26 types.
27 27
28 28 * Allow observers to register callbacks for events from individual or all
29 29 notifying objects.
30 30
31 31 * Notification to the observer consists of the notification type, notifying
32 32 object and user-supplied extra information [implementation: as keyword
33 33 parameters to the registered callback].
34 34
35 35 * Perform as O(1) in the case of no registered observers.
36 36
37 37 * Permit out-of-process or cross-network extension.
38 38
39 39 What's not included
40 40 ===================
41 41
42 As written, the :mod:`IPython.kernel.core.notificaiton` module does not:
42 As written, the :mod:`IPython.kernel.core.notification` module does not:
43 43
44 44 * Provide out-of-process or network notifications (these should be handled by
45 45 a separate, Twisted aware module in :mod:`IPython.kernel`).
46 46
47 * Provide zope.interface-style interfaces for the notification system (these
47 * Provide zope.interface style interfaces for the notification system (these
48 48 should also be provided by the :mod:`IPython.kernel` module).
49 49
50 50 Use Cases
51 51 =========
52 52
53 The following use cases describe the main intended uses of the notificaiton module and illustrate the main success scenario for each use case:
53 The following use cases describe the main intended uses of the notification
54 module and illustrate the main success scenario for each use case:
54 55
55 1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code::
56 Scenario 1
57 ----------
56 58
57 from IPython.kernel.core.notification import NotificationCenter
58 center = NotificationCenter.sharedNotificationCenter
59 center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification)
60
61 and elsewhere in his front end::
59 Dwight Schroot is writing a frontend for the IPython project. His frontend is
60 stuck in the stone age and must communicate synchronously with an
61 :mod:`IPython.kernel.core.Interpreter` instance. Because code is executed in blocks
62 by the Interpreter, Dwight's UI freezes every time he executes a long block of
63 code. To keep track of the progress of his long running block, Dwight adds the
64 following code to his frontend's set-up code::
65
66 from IPython.kernel.core.notification import NotificationCenter
67 center = NotificationCenter.sharedNotificationCenter
68 center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification)
62 69
63 def stdout_notification(self, type, notifying_object, out_string=None):
64 self.writeStdOut(out_string)
70 and elsewhere in his front end::
71
72 def stdout_notification(self, type, notifying_object, out_string=None):
73 self.writeStdOut(out_string)
65 74
66 75 If everything works, the Interpreter will (according to its published API)
67 76 fire a notification via the
68 77 :data:`IPython.kernel.core.notification.sharedCenter` of type
69 78 :const:`STD_OUT_NOTIFICATION_TYPE` before writing anything to stdout [it's up
70 79 to the Intereter implementation to figure out when to do this]. The
71 80 notificaiton center will then call the registered callbacks for that event
72 81 type (in this case, Dwight's frontend's stdout_notification method). Again,
73 82 according to its API, the Interpreter provides an additional keyword argument
74 83 when firing the notificaiton of out_string, a copy of the string it will write
75 84 to stdout.
76 85
77 86 Like magic, Dwight's frontend is able to provide output, even during
78 87 long-running calculations. Now if Jim could just convince Dwight to use
79 88 Twisted...
80 89
81 2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is
90 Scenario 2
91 ----------
92
93 Boss Hog is writing a frontend for the IPython project. Because Boss Hog is
82 94 stuck in the stone age, his frontend will be written in a new Fortran-like
83 95 dialect of python and will run only from the command line. Because he doesn't
84 96 need any fancy notification system and is used to worrying about every cycle
85 97 on his rat-wheel powered mini, Boss Hog is adamant that the new notification
86 98 system not produce any performance penalty. As they say in Hazard county,
87 99 there's no such thing as a free lunch. If he wanted zero overhead, he should
88 100 have kept using IPython 0.8. Instead, those tricky Duke boys slide in a
89 101 suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module
90 102 that imparts only a constant (and small) performance penalty when the
91 103 Interpreter (or any other object) fires an event for which there are no
92 104 registered observers. Of course, the same notificaiton-enabled Interpreter can
93 105 then be used in frontends that require notifications, thus saving the IPython
94 106 project from a nasty civil war.
95
96 3. Barry is wrting a frontend for the IPython project. Because Barry's front
97 end is the *new hotness*, it uses an asynchronous event model to communicate
98 with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the
99 IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the
107
108 Scenario 3
109 ----------
110
111 Barry is wrting a frontend for the IPython project. Because Barry's front end
112 is the *new hotness*, it uses an asynchronous event model to communicate with
113 a Twisted :mod:`IPython.kernel.engineservice` that communicates with the
114 IPython :class:`IPython.kernel.core.interpreter.Interpreter`. Using the
100 115 :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the
101 116 :mod:`IPython.kernel.core.notification` module, Barry's frontend can register
102 117 for notifications from the interpreter that are delivered asynchronously. Even
103 118 if Barry's frontend is running on a separate process or even host from the
104 119 Interpreter, the notifications are delivered, as if by dark and twisted magic.
105 Just like Dwight's frontend, Barry's frontend can now recieve notifications of
120 Just like Dwight's frontend, Barry's frontend can now receive notifications of
106 121 e.g. writing to stdout/stderr, opening/closing an external file, an exception
107 122 in the executing code, etc.
108 123
This diff has been collapsed as it changes many lines, (510 lines changed) Show them Hide them
@@ -1,518 +1,8 b''
1 .. _development:
2 1
3 ==============================
4 IPython development guidelines
5 ==============================
6 2
7 3
8 Overview
9 ========
10 4
11 This document describes IPython from the perspective of developers. Most
12 importantly, it gives information for people who want to contribute to the
13 development of IPython. So if you want to help out, read on!
14 5
15 How to contribute to IPython
16 ============================
17 6
18 IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
19 This makes it easy for people to contribute to the development of IPython.
20 There are several ways in which you can join in.
21 7
22 If you have a small change that you want to send to the team, you can edit your
23 bazaar checkout of IPython (see below) in-place, and ask bazaar for the
24 differences::
25
26 $ cd /path/to/your/copy/of/ipython
27 $ bzr diff > my_fixes.diff
28
29 This produces a patch file with your fixes, which we can apply to the source
30 tree. This file should then be attached to a ticket in our `bug tracker
31 <https://bugs.launchpad.net/ipython>`_, indicating what it does.
32
33 This model of creating small, self-contained patches works very well and there
34 are open source projects that do their entire development this way. However,
35 in IPython we have found that for tracking larger changes, making use of
36 bazaar's full capabilities in conjunction with Launchpad's code hosting
37 services makes for a much better experience.
38
39 Making your own branch of IPython allows you to refine your changes over time,
40 track the development of the main team, and propose your own full version of
41 the code for others to use and review, with a minimum amount of fuss. The next
42 parts of this document will explain how to do this.
43
44 Install Bazaar and create a Launchpad account
45 ---------------------------------------------
46
47 First make sure you have installed Bazaar (see their `website
48 <http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
49 you, try the following::
50
51 $ bzr whoami
52 Joe Coder <jcoder@gmail.com>
53
54 This should display your name and email. Next, you will want to create an
55 account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
56 ssh keys. For more information of setting up your ssh keys, see `this link
57 <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
58
59 Get the main IPython branch from Launchpad
60 ------------------------------------------
61
62 Now, you can get a copy of the main IPython development branch (we call this
63 the "trunk")::
64
65 $ bzr branch lp:ipython
66
67 Create a working branch
68 -----------------------
69
70 When working on IPython, you won't actually make edits directly to the
71 :file:`lp:ipython` branch. Instead, you will create a separate branch for your
72 changes. For now, let's assume you want to do your work in a branch named
73 "ipython-mybranch". Create this branch by doing::
74
75 $ bzr branch ipython ipython-mybranch
76
77 When you actually create a branch, you will want to give it a name that
78 reflects the nature of the work that you will be doing in it, like
79 "install-docs-update".
80
81 Make edits in your working branch
82 ---------------------------------
83
84 Now you are ready to actually make edits in your :file:`ipython-mybranch`
85 branch. Before doing this, it is helpful to install this branch so you can
86 test your changes as you work. This is easiest if you have setuptools
87 installed. Then, just do::
88
89 $ cd ipython-mybranch
90 $ python setupegg.py develop
91
92 Now, make some changes. After a while, you will want to commit your changes.
93 This let's Bazaar know that you like the changes you have made and gives you
94 an opportunity to keep a nice record of what you have done. This looks like
95 this::
96
97 $ ...do work in ipython-mybranch...
98 $ bzr commit -m "the commit message goes here"
99
100 Please note that since we now don't use an old-style linear ChangeLog (that
101 tends to cause problems with distributed version control systems), you should
102 ensure that your log messages are reasonably detailed. Use a docstring-like
103 approach in the commit messages (including the second line being left
104 *blank*)::
105
106 Single line summary of changes being committed.
107
108 * more details when warranted ...
109 * including crediting outside contributors if they sent the
110 code/bug/idea!
111
112 As you work, you will repeat this edit/commit cycle many times. If you work on
113 your branch for a long time, you will also want to get the latest changes from
114 the :file:`lp:ipython` branch. This can be done with the following sequence of
115 commands::
116
117 $ ls
118 ipython
119 ipython-mybranch
120
121 $ cd ipython
122 $ bzr pull
123 $ cd ../ipython-mybranch
124 $ bzr merge ../ipython
125 $ bzr commit -m "Merging changes from trunk"
126
127 Along the way, you should also run the IPython test suite. You can do this
128 using the :command:`iptest` command (which is basically a customized version of
129 :command:`nosetests`)::
130
131 $ cd
132 $ iptest
133
134 The :command:`iptest` command will also pick up and run any tests you have
135 written. See :ref:`testing documentation <devel_testing>` for further details
136 on the testing system.
137
138
139 Post your branch and request a code review
140 ------------------------------------------
141
142 Once you are done with your edits, you should post your branch on Launchpad so
143 that other IPython developers can review the changes and help you merge your
144 changes into the main development branch. To post your branch on Launchpad,
145 do::
146
147 $ cd ipython-mybranch
148 $ bzr push lp:~yourusername/ipython/ipython-mybranch
149
150 Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
151 should see your branch under the "Code" tab. If you click on your branch, you
152 can provide a short description of the branch as well as mark its status. Most
153 importantly, you should click the link that reads "Propose for merging into
154 another branch". What does this do?
155
156 This let's the other IPython developers know that your branch is ready to be
157 reviewed and merged into the main development branch. During this review
158 process, other developers will give you feedback and help you get your code
159 ready to be merged. What types of things will we be looking for:
160
161 * All code is documented.
162 * All code has tests.
163 * The entire IPython test suite passes.
164
165 Once your changes have been reviewed and approved, someone will merge them
166 into the main development branch.
167
168
169 Some notes for core developers when merging third-party contributions
170 =====================================================================
171
172 Core developers, who ultimately merge any approved branch (from themselves,
173 another developer, or any third-party contribution) will typically use
174 :command:`bzr merge` to merge the branch into the trunk and push it to the
175 main Launcphad site. This is a short list of things to keep in mind when doing
176 this process, so that the project history is easy to understand in the long
177 run, and that generating release notes is as painless and accurate as
178 possible.
179
180 - When you merge any non-trivial functionality (from one small bug fix to a
181 big feature branch), please remember to always edit the :file:`changes.txt`
182 file accordingly. This file has one main section for each release, and if
183 you edit it as you go, noting what new features, bug fixes or API changes
184 you have made, the release notes will be almost finished when they are
185 needed later. This is much easier if done when you merge the work, rather
186 than weeks or months later by re-reading a massive Bazaar log.
187
188 - When big merges are done, the practice of putting a summary commit message
189 in the merge is *extremely* useful. It makes this kind of job much nicer,
190 because that summary log message can be almost copy/pasted without changes,
191 if it was well written, rather than dissecting the next-level messages from
192 the individual commits.
193
194 - It's important that we remember to always credit who gave us something if
195 it's not the committer. In general, we have been fairly good on this front,
196 this is just a reminder to keep things up. As a note, if you are ever
197 committing something that is completely (or almost so) a third-party
198 contribution, do the commit as::
199
200 $ bzr commit --author="Someone Else"
201
202 This way it will show that name separately in the log, which makes it even
203 easier to spot. Obviously we often rework third party contributions
204 extensively, but this is still good to keep in mind for cases when we don't
205 touch the code too much.
206
207
208 Documentation
209 =============
210
211 Standalone documentation
212 ------------------------
213
214 All standalone documentation should be written in plain text (``.txt``) files
215 using reStructuredText [reStructuredText]_ for markup and formatting. All such
216 documentation should be placed in directory :file:`docs/source` of the IPython
217 source tree. The documentation in this location will serve as the main source
218 for IPython documentation and all existing documentation should be converted
219 to this format.
220
221 To build the final documentation, we use Sphinx [Sphinx]_. Once you have
222 Sphinx installed, you can build the html docs yourself by doing::
223
224 $ cd ipython-mybranch/docs
225 $ make html
226
227 Docstring format
228 ----------------
229
230 Good docstrings are very important. All new code should have docstrings that
231 are formatted using reStructuredText for markup and formatting, since it is
232 understood by a wide variety of tools. Details about using reStructuredText
233 for docstrings can be found `here
234 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
235
236 Additional PEPs of interest regarding documentation of code:
237
238 * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
239 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
240 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
241
242
243 Coding conventions
244 ==================
245
246 General
247 -------
248
249 In general, we'll try to follow the standard Python style conventions as
250 described here:
251
252 * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
253
254
255 Other comments:
256
257 * In a large file, top level classes and functions should be
258 separated by 2-3 lines to make it easier to separate them visually.
259 * Use 4 spaces for indentation.
260 * Keep the ordering of methods the same in classes that have the same
261 methods. This is particularly true for classes that implement an interface.
262
263 Naming conventions
264 ------------------
265
266 In terms of naming conventions, we'll follow the guidelines from the `Style
267 Guide for Python Code`_.
268
269 For all new IPython code (and much existing code is being refactored), we'll
270 use:
271
272 * All ``lowercase`` module names.
273
274 * ``CamelCase`` for class names.
275
276 * ``lowercase_with_underscores`` for methods, functions, variables and
277 attributes.
278
279 There are, however, some important exceptions to these rules. In some cases,
280 IPython code will interface with packages (Twisted, Wx, Qt) that use other
281 conventions. At some level this makes it impossible to adhere to our own
282 standards at all times. In particular, when subclassing classes that use other
283 naming conventions, you must follow their naming conventions. To deal with
284 cases like this, we propose the following policy:
285
286 * If you are subclassing a class that uses different conventions, use its
287 naming conventions throughout your subclass. Thus, if you are creating a
288 Twisted Protocol class, used Twisted's
289 ``namingSchemeForMethodsAndAttributes.``
290
291 * All IPython's official interfaces should use our conventions. In some cases
292 this will mean that you need to provide shadow names (first implement
293 ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
294 costs, but it will probably be necessary at times. But, please use this
295 sparingly!
296
297 Implementation-specific *private* methods will use
298 ``_single_underscore_prefix``. Names with a leading double underscore will
299 *only* be used in special cases, as they makes subclassing difficult (such
300 names are not easily seen by child classes).
301
302 Occasionally some run-in lowercase names are used, but mostly for very short
303 names or where we are implementing methods very similar to existing ones in a
304 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
305 established precedent).
306
307 The old IPython codebase has a big mix of classes and modules prefixed with an
308 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
309 upon, as namespaces offer cleaner prefixing. The only case where this approach
310 is justified is for classes which are expected to be imported into external
311 namespaces and a very generic name (like Shell) is too likely to clash with
312 something else. We'll need to revisit this issue as we clean up and refactor
313 the code, but in general we should remove as many unnecessary ``IP``/``ip``
314 prefixes as possible. However, if a prefix seems absolutely necessary the more
315 specific ``IPY`` or ``ipy`` are preferred.
316
317 .. _devel_testing:
318
319 Testing system
320 ==============
321
322 It is extremely important that all code contributed to IPython has tests.
323 Tests should be written as unittests, doctests or as entities that the Nose
324 [Nose]_ testing package will find. Regardless of how the tests are written, we
325 will use Nose for discovering and running the tests. Nose will be required to
326 run the IPython test suite, but will not be required to simply use IPython.
327
328 Tests of Twisted using code need to follow two additional guidelines:
329
330 1. Twisted using tests should be written by subclassing the :class:`TestCase`
331 class that comes with :mod:`twisted.trial.unittest`.
332
333 2. All :class:`Deferred` instances that are created in the test must be
334 properly chained and the final one *must* be the return value of the test
335 method.
336
337 When these two things are done, Nose will be able to run the tests and the
338 twisted reactor will be handled correctly.
339
340 Each subpackage in IPython should have its own :file:`tests` directory that
341 contains all of the tests for that subpackage. This allows each subpackage to
342 be self-contained. A good convention to follow is to have a file named
343 :file:`test_foo.py` for each module :file:`foo.py` in the package. This makes
344 it easy to organize the tests, though like most conventions, it's OK to break
345 it if logic and common sense dictate otherwise.
346
347 If a subpackage has any dependencies beyond the Python standard library, the
348 tests for that subpackage should be skipped if the dependencies are not
349 found. This is very important so users don't get tests failing simply because
350 they don't have dependencies. We ship a set of decorators in the
351 :mod:`IPython.testing` package to tag tests that may be platform-specific or
352 otherwise may have restrictions; if the existing ones don't fit your needs, add
353 a new decorator in that location so other tests can reuse it.
354
355 To run the IPython test suite, use the :command:`iptest` command that is
356 installed with IPython (if you are using IPython in-place, without installing
357 it, you can find this script in the :file:`scripts` directory)::
358
359 $ iptest
360
361 This command colects all IPython tests into separate groups, and then calls
362 either Nose with the proper options and extensions, or Twisted's
363 :command:`trial`. This ensures that tests that need the Twisted reactor
364 management facilities execute separate of Nose. If any individual test group
365 fails, :command:`iptest` will print what you need to type so you can rerun that
366 particular test group alone for debugging.
367
368 By default, :command:`iptest` runs the entire IPython test
369 suite (skipping tests that may be platform-specific or which depend on tools
370 you may not have). But you can also use it to run only one specific test file,
371 or a specific test function. For example, this will run only the
372 :file:`test_magic` file from the test suite::
373
374 $ iptest IPython.tests.test_magic
375 ----------------------------------------------------------------------
376 Ran 10 tests in 0.348s
377
378 OK (SKIP=3)
379 Deleting object: second_pass
380
381 while the ``path:function`` syntax allows you to select a specific function in
382 that file to run::
383
384 $ iptest IPython.tests.test_magic:test_obj_del
385 ----------------------------------------------------------------------
386 Ran 1 test in 0.204s
387
388 OK
389
390 Since :command:`iptest` is based on nosetests, you can pass it any regular
391 nosetests option. For example, you can use ``--pdb`` or ``--pdb-failures`` to
392 automatically activate the interactive Pdb debugger on errors or failures. See
393 the nosetests documentation for further details.
394
395
396 A few tips for writing tests
397 ----------------------------
398
399 You can write tests either as normal test files, using all the conventions that
400 Nose recognizes, or as doctests. Note that *all* IPython functions should have
401 at least one example that serves as a doctest, whenever technically feasible.
402 However, example doctests should only be in the main docstring if they are *a
403 good example*, i.e. if they convey useful information about the function. If
404 you simply would like to write a test as a doctest, put it in a separate test
405 file and write a no-op function whose only purpose is its docstring.
406
407 Note, however, that in a file named :file:`test_X`, functions whose only test
408 is their docstring (as a doctest) and which have no test functionality of their
409 own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
410 double-counted (the empty function call is counted as a test, which just
411 inflates tests numbers artificially). This restriction does not apply to
412 functions in files with other names, due to how Nose discovers tests.
413
414 You can use IPython examples in your docstrings. Those can make full use of
415 IPython functionality (magics, variable substitution, etc), but be careful to
416 keep them generic enough that they run identically on all Operating Systems.
417
418 The prompts in your doctests can be either of the plain Python ``>>>`` variety
419 or ``In [1]:`` IPython style. Since this is the IPython system, after all, we
420 encourage you to use IPython prompts throughout, unless you are illustrating a
421 specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
422
423 If a test isn't safe to run inside the main nose process (e.g. because it loads
424 a GUI toolkit), consider running it in a subprocess and capturing its output
425 for evaluation and test decision later. Here is an example of how to do it, by
426 relying on the builtin ``_ip`` object that contains the public IPython api as
427 defined in :mod:`IPython.ipapi`::
428
429 def test_obj_del():
430 """Test that object's __del__ methods are called on exit."""
431 test_dir = os.path.dirname(__file__)
432 del_file = os.path.join(test_dir,'obj_del.py')
433 out = _ip.IP.getoutput('ipython %s' % del_file)
434 nt.assert_equals(out,'object A deleted')
435
436
437
438 If a doctest contains input whose output you don't want to verify identically
439 via doctest (random output, an object id, etc), you can mark a docstring with
440 ``#random``. All of these test will have their code executed but no output
441 checking will be done::
442
443 >>> 1+3
444 junk goes here... # random
445
446 >>> 1+2
447 again, anything goes #random
448 if multiline, the random mark is only needed once.
449
450 >>> 1+2
451 You can also put the random marker at the end:
452 # random
453
454 >>> 1+2
455 # random
456 .. or at the beginning.
457
458 In a case where you want an *entire* docstring to be executed but not verified
459 (this only serves to check that the code runs without crashing, so it should be
460 used very sparingly), you can put ``# all-random`` in the docstring.
461
462 .. _devel_config:
463
464 Release checklist
465 =================
466
467 Most of the release process is automated by the :file:`release` script in the
468 :file:`tools` directory. This is just a handy reminder for the release manager.
469
470 #. First, run :file:`build_release`, which does all the file checking and
471 building that the real release script will do. This will let you do test
472 installations, check that the build procedure runs OK, etc. You may want to
473 disable a few things like multi-version RPM building while testing, because
474 otherwise the build takes really long.
475
476 #. Run the release script, which makes the tar.gz, eggs and Win32 .exe
477 installer. It posts them to the site and registers the release with PyPI.
478
479 #. Updating the website with announcements and links to the updated
480 changes.txt in html form. Remember to put a short note both on the news
481 page of the site and on Launcphad.
482
483 #. Drafting a short release announcement with i) highlights and ii) a link to
484 the html changes.txt.
485
486 #. Make sure that the released version of the docs is live on the site.
487
488 #. Celebrate!
489
490 Porting to 3.0
491 ==============
492
493 There are no definite plans for porting of IPython to python 3. The major
494 issue is the dependency on twisted framework for the networking/threading
495 stuff. It is possible that it the traditional IPython interactive console
496 could be ported more easily since it has no such dependency. Here are a few
497 things that will need to be considered when doing such a port especially
498 if we want to have a codebase that works directly on both 2.x and 3.x.
499
500 1. The syntax for exceptions changed (PEP 3110). The old
501 `except exc, var` changed to `except exc as var`. At last
502 count there was 78 occurences of this usage in the codebase. This
503 is a particularly problematic issue, because it's not easy to
504 implement it in a 2.5-compatible way.
505
506 Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
507 will likely at some point put out a release that requires strictly 2.6 and
508 abandons 2.5 compatibility. This will then allow us to port the code to using
509 :func:`print` as a function, `except exc as var` syntax, etc. But as of
510 version 0.11 at least, we will retain Python 2.5 compatibility.
511
512
513 .. [Bazaar] Bazaar. http://bazaar-vcs.org/
514 .. [Launchpad] Launchpad. http://www.launchpad.net/ipython
515 .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html
516 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
517 .. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
518 8
@@ -1,94 +1,114 b''
1 1 .. _roadmap:
2 2
3 3 ===================
4 4 Development roadmap
5 5 ===================
6 6
7 7 IPython is an ambitious project that is still under heavy development.
8 8 However, we want IPython to become useful to as many people as possible, as
9 9 quickly as possible. To help us accomplish this, we are laying out a roadmap
10 10 of where we are headed and what needs to happen to get there. Hopefully, this
11 11 will help the IPython developers figure out the best things to work on for
12 12 each upcoming release.
13 13
14 14 Work targeted to particular releases
15 15 ====================================
16 16
17 17 Release 0.11
18 18 ------------
19 19
20 20 * Full module and package reorganization (done).
21 21
22 22 * Removal of the threaded shells and new implementation of GUI support
23 23 based on ``PyOSInputHook`` (done).
24 24
25 25 * Refactor the configuration system (done).
26 26
27 27 * Prepare to refactor IPython's core by creating a new component and
28 28 application system (done).
29 29
30 30 * Start to refactor IPython's core by turning everything into components
31 31 (started).
32 32
33 33 Release 0.12
34 34 ------------
35 35
36 36 * Continue to refactor IPython's core by turning everything into components.
37 37
38 38
39 39 Major areas of work
40 40 ===================
41 41
42 42 Refactoring the main IPython core
43 43 ---------------------------------
44 44
45 45 During the summer of 2009, we began refactoring IPython's core. The main
46 46 thrust in this work was make the IPython core into a set of loosely coupled
47 47 components. The base component class for this is
48 48 :class:`IPython.core.component.Component`. This section outlines the status
49 49 of this work.
50 50
51 51 Parts of the IPython core that have been turned into components:
52 52
53 53 * The main :class:`InteractiveShell` class.
54 54 * The aliases (:mod:`IPython.core.aliases`).
55 55 * The display and builtin traps (:mod:`IPython.core.display_trap` and
56 56 :mod:`IPython.core.builtin_trap`).
57 57 * The prefilter machinery (:mod:`IPython.core.prefilter`).
58 58
59 59 Parts of the IPythoncore that need to be turned into components:
60 60
61 61 * Magics.
62 62 * Input and output history management.
63 63 * Prompts.
64 64 * Completers.
65 65 * Logging.
66 66 * Exception handling.
67 67 * Anything else.
68 68
69 69 Process management for :mod:`IPython.kernel`
70 70 --------------------------------------------
71 71
72 72 Performance problems
73 73 --------------------
74 74
75 75 Currently, we have a number of performance issues in :mod:`IPython.kernel`:
76 76
77 77 * The controller stores a large amount of state in Python dictionaries. Under
78 78 heavy usage, these dicts with get very large, causing memory usage problems.
79 79 We need to develop more scalable solutions to this problem. This will also
80 80 help the controller to be more fault tolerant.
81 81
82 82 * We currently don't have a good way of handling large objects in the
83 83 controller. The biggest problem is that because we don't have any way of
84 84 streaming objects, we get lots of temporary copies in the low-level buffers.
85 85 We need to implement a better serialization approach and true streaming
86 86 support.
87 87
88 88 * The controller currently unpickles and repickles objects. We need to use the
89 89 [push|pull]_serialized methods instead.
90 90
91 91 * Currently the controller is a bottleneck. The best approach for this is to
92 92 separate the controller itself into multiple processes, one for the core
93 93 controller and one each for the controller interfaces.
94 94
95 Porting to 3.0
96 ==============
97
98 There are no definite plans for porting of IPython to Python 3. The major
99 issue is the dependency on Twisted framework for the networking/threading
100 stuff. It is possible that it the traditional IPython interactive console
101 could be ported more easily since it has no such dependency. Here are a few
102 things that will need to be considered when doing such a port especially
103 if we want to have a codebase that works directly on both 2.x and 3.x.
104
105 1. The syntax for exceptions changed (PEP 3110). The old `except exc, var`
106 changed to `except exc as var`. At last count there was 78 occurrences of this
107 usage in the code base. This is a particularly problematic issue, because it's
108 not easy to implement it in a 2.5-compatible way.
109
110 Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
111 will likely at some point put out a release that requires strictly 2.6 and
112 abandons 2.5 compatibility. This will then allow us to port the code to using
113 :func:`print` as a function, `except exc as var` syntax, etc. But as of
114 version 0.11 at least, we will retain Python 2.5 compatibility.
@@ -1,96 +1,93 b''
1 1 .. _faq:
2 2
3 3 ========================================
4 4 Frequently asked questions
5 5 ========================================
6 6
7 7 General questions
8 8 =================
9 9
10 10 Questions about parallel computing with IPython
11 11 ================================================
12 12
13 13 Will IPython speed my Python code up?
14 14 --------------------------------------
15 15
16 16 Yes and no. When converting a serial code to run in parallel, there often many
17 17 difficulty questions that need to be answered, such as:
18 18
19 19 * How should data be decomposed onto the set of processors?
20 20
21 21 * What are the data movement patterns?
22 22
23 23 * Can the algorithm be structured to minimize data movement?
24 24
25 25 * Is dynamic load balancing important?
26 26
27 27 We can't answer such questions for you. This is the hard (but fun) work of parallel
28 28 computing. But, once you understand these things IPython will make it easier for you to
29 29 implement a good solution quickly. Most importantly, you will be able to use the
30 30 resulting parallel code interactively.
31 31
32 32 With that said, if your problem is trivial to parallelize, IPython has a number of
33 33 different interfaces that will enable you to parallelize things is almost no time at
34 34 all. A good place to start is the ``map`` method of our :class:`MultiEngineClient`.
35 35
36 36 What is the best way to use MPI from Python?
37 37 --------------------------------------------
38 38
39 39 What about all the other parallel computing packages in Python?
40 40 ---------------------------------------------------------------
41 41
42 42 Some of the unique characteristic of IPython are:
43 43
44 44 * IPython is the only architecture that abstracts out the notion of a
45 45 parallel computation in such a way that new models of parallel computing
46 46 can be explored quickly and easily. If you don't like the models we
47 47 provide, you can simply create your own using the capabilities we provide.
48 48
49 49 * IPython is asynchronous from the ground up (we use `Twisted`_).
50 50
51 51 * IPython's architecture is designed to avoid subtle problems
52 52 that emerge because of Python's global interpreter lock (GIL).
53 53
54 54 * While IPython's architecture is designed to support a wide range
55 55 of novel parallel computing models, it is fully interoperable with
56 56 traditional MPI applications.
57 57
58 58 * IPython has been used and tested extensively on modern supercomputers.
59 59
60 60 * IPython's networking layers are completely modular. Thus, is
61 61 straightforward to replace our existing network protocols with
62 62 high performance alternatives (ones based upon Myranet/Infiniband).
63 63
64 64 * IPython is designed from the ground up to support collaborative
65 65 parallel computing. This enables multiple users to actively develop
66 66 and run the *same* parallel computation.
67 67
68 68 * Interactivity is a central goal for us. While IPython does not have
69 69 to be used interactivly, it can be.
70 70
71 71 .. _Twisted: http://www.twistedmatrix.com
72 72
73 73 Why The IPython controller a bottleneck in my parallel calculation?
74 74 -------------------------------------------------------------------
75 75
76 76 A golden rule in parallel computing is that you should only move data around if you
77 77 absolutely need to. The main reason that the controller becomes a bottleneck is that
78 78 too much data is being pushed and pulled to and from the engines. If your algorithm
79 79 is structured in this way, you really should think about alternative ways of
80 80 handling the data movement. Here are some ideas:
81 81
82 82 1. Have the engines write data to files on the locals disks of the engines.
83 83
84 84 2. Have the engines write data to files on a file system that is shared by
85 85 the engines.
86 86
87 87 3. Have the engines write data to a database that is shared by the engines.
88 88
89 89 4. Simply keep data in the persistent memory of the engines and move the
90 90 computation to the data (rather than the data to the computation).
91 91
92 92 5. See if you can pass data directly between engines using MPI.
93 93
94 Isn't Python slow to be used for high-performance parallel computing?
95 ---------------------------------------------------------------------
96
@@ -1,34 +1,33 b''
1 1 =====================
2 2 IPython Documentation
3 3 =====================
4 4
5 5 .. htmlonly::
6 6
7 7 :Release: |release|
8 8 :Date: |today|
9 9
10 Welcome to the official IPython documentation. This document describes the
11 various parts of IPython that are relevant to both users and developers.
10 Welcome to the official IPython documentation.
12 11
13 12 Contents
14 13 ========
15 14
16 15 .. toctree::
17 16 :maxdepth: 1
18 17
19 18 overview.txt
20 19 whatsnew/index.txt
21 20 install/index.txt
22 21 interactive/index.txt
23 22 parallel/index.txt
24 23 config/index.txt
25 24 development/index.txt
26 25 api/index.txt
27 26 faq.txt
28 27 about/index.txt
29 28
30 29 .. htmlonly::
31 30 * :ref:`genindex`
32 31 * :ref:`modindex`
33 32 * :ref:`search`
34 33
@@ -1,294 +1,328 b''
1 1 Overview
2 2 ========
3 3
4 4 This document describes the steps required to install IPython. IPython is
5 5 organized into a number of subpackages, each of which has its own dependencies.
6 6 All of the subpackages come with IPython, so you don't need to download and
7 7 install them separately. However, to use a given subpackage, you will need to
8 8 install all of its dependencies.
9 9
10 10
11 11 Please let us know if you have problems installing IPython or any of its
12 12 dependencies. Officially, IPython requires Python version 2.5 or 2.6. We
13 13 have *not* yet started to port IPython to Python 3.0.
14 14
15 15 .. warning::
16 16
17 17 Officially, IPython supports Python versions 2.5 and 2.6.
18 18
19 19 IPython 0.10 has only been well tested with Python 2.5 and 2.6. Parts of
20 20 it may work with Python 2.4, but we do not officially support Python 2.4
21 21 anymore. If you need to use 2.4, you can still run IPython 0.9.
22 22
23 23 Some of the installation approaches use the :mod:`setuptools` package and its
24 24 :command:`easy_install` command line program. In many scenarios, this provides
25 25 the most simple method of installing IPython and its dependencies. It is not
26 26 required though. More information about :mod:`setuptools` can be found on its
27 27 website.
28 28
29 29 More general information about installing Python packages can be found in
30 30 Python's documentation at http://www.python.org/doc/.
31 31
32 32 Quickstart
33 33 ==========
34 34
35 35 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
36 36 Windows), the following will download and install IPython *and* the main
37 optional dependencies::
37 optional dependencies:
38 38
39 $ easy_install ipython[kernel,security,test]
39 .. code-block:: bash
40
41 easy_install ipython[kernel,security,test]
40 42
41 43 This will get Twisted, zope.interface and Foolscap, which are needed for
42 44 IPython's parallel computing features as well as the nose package, which will
43 45 enable you to run IPython's test suite. To run IPython's test suite, use the
44 :command:`iptest` command::
46 :command:`iptest` command:
47
48 .. code-block:: bash
45 49
46 $ iptest
50 iptest
47 51
48 52 Read on for more specific details and instructions for Windows.
49 53
50 54 Installing IPython itself
51 55 =========================
52 56
53 57 Given a properly built Python, the basic interactive IPython shell will work
54 58 with no external dependencies. However, some Python distributions
55 59 (particularly on Windows and OS X), don't come with a working :mod:`readline`
56 60 module. The IPython shell will work without :mod:`readline`, but will lack
57 61 many features that users depend on, such as tab completion and command line
58 62 editing. See below for details of how to make sure you have a working
59 63 :mod:`readline`.
60 64
61 65 Installation using easy_install
62 66 -------------------------------
63 67
64 68 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
65 to simple use :command:`easy_install`::
69 to simple use :command:`easy_install`:
66 70
67 $ easy_install ipython
71 .. code-block:: bash
72
73 easy_install ipython
68 74
69 75 That's it.
70 76
71 77 Installation from source
72 78 ------------------------
73 79
74 80 If you don't want to use :command:`easy_install`, or don't have it installed,
75 81 just grab the latest stable build of IPython from `here
76 <http://ipython.scipy.org/dist/>`_. Then do the following::
82 <http://ipython.scipy.org/dist/>`_. Then do the following:
83
84 .. code-block:: bash
77 85
78 $ tar -xzf ipython.tar.gz
79 $ cd ipython
80 $ python setup.py install
86 tar -xzf ipython.tar.gz
87 cd ipython
88 python setup.py install
81 89
82 90 If you are installing to a location (like ``/usr/local``) that requires higher
83 91 permissions, you may need to run the last command with :command:`sudo`.
84 92
85 93 Windows
86 94 -------
87 95
88 96 There are a few caveats for Windows users. The main issue is that a basic
89 97 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
90 98 shortcuts, which most users want. To get an installation with these, you can
91 99 use any of the following alternatives:
92 100
93 101 1. Install using :command:`easy_install`.
94 102
95 103 2. Install using our binary ``.exe`` Windows installer, which can be found at
96 104 `here <http://ipython.scipy.org/dist/>`_
97 105
98 106 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
99 107 install``).
100 108
101 IPython by default runs in a termninal window, but the normal terminal
109 IPython by default runs in a terminal window, but the normal terminal
102 110 application supplied by Microsoft Windows is very primitive. You may want to
103 111 download the excellent and free Console_ application instead, which is a far
104 112 superior tool. You can even configure Console to give you by default an
105 113 IPython tab, which is very convenient to create new IPython sessions directly
106 114 from the working terminal.
107 115
108 116 .. _Console: http://sourceforge.net/projects/console
109 117
110 118
111 119 Installing the development version
112 120 ----------------------------------
113 121
114 122 It is also possible to install the development version of IPython from our
115 123 `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
116 need to have Bazaar installed on your system. Then just do::
124 need to have Bazaar installed on your system. Then just do:
117 125
118 $ bzr branch lp:ipython
119 $ cd ipython
120 $ python setup.py install
126 .. code-block:: bash
127
128 bzr branch lp:ipython
129 cd ipython
130 python setup.py install
121 131
122 132 Again, this last step on Windows won't create ``.bat`` files or Start Menu
123 133 shortcuts, so you will have to use one of the other approaches listed above.
124 134
125 135 Some users want to be able to follow the development branch as it changes. If
126 136 you have :mod:`setuptools` installed, this is easy. Simply replace the last
127 step by::
137 step by:
138
139 .. code-block:: bash
128 140
129 $ python setupegg.py develop
141 python setupegg.py develop
130 142
131 143 This creates links in the right places and installs the command line script to
132 144 the appropriate places. Then, if you want to update your IPython at any time,
133 just do::
145 just do:
146
147 .. code-block:: bash
134 148
135 $ bzr pull
149 bzr pull
136 150
137 151 Basic optional dependencies
138 152 ===========================
139 153
140 154 There are a number of basic optional dependencies that most users will want to
141 155 get. These are:
142 156
143 157 * readline (for command line editing, tab completion, etc.)
144 158 * nose (to run the IPython test suite)
145 159 * pexpect (to use things like irunner)
146 160
147 161 If you are comfortable installing these things yourself, have at it, otherwise
148 162 read on for more details.
149 163
150 164 readline
151 165 --------
152 166
153 167 In principle, all Python distributions should come with a working
154 168 :mod:`readline` module. But, reality is not quite that simple. There are two
155 169 common situations where you won't have a working :mod:`readline` module:
156 170
157 171 * If you are using the built-in Python on Mac OS X.
158 172
159 173 * If you are running Windows, which doesn't have a :mod:`readline` module.
160 174
161 175 On OS X, the built-in Python doesn't not have :mod:`readline` because of
162 176 license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
163 177 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
164 178 many of the issues related to the differences between readline and libedit have
165 179 been resolved. For many users, libedit may be sufficient.
166 180
167 181 Most users on OS X will want to get the full :mod:`readline` module. To get a
168 working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
182 working :mod:`readline` module, just do (with :mod:`setuptools` installed):
169 183
170 $ easy_install readline
184 .. code-block:: bash
185
186 easy_install readline
171 187
172 188 .. note:
173 189
174 190 Other Python distributions on OS X (such as fink, MacPorts and the
175 191 official python.org binaries) already have readline installed so
176 192 you don't have to do this step.
177 193
178 194 If needed, the readline egg can be build and installed from source (see the
179 195 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
180 196
181 197 On Windows, you will need the PyReadline module. PyReadline is a separate,
182 198 Windows only implementation of readline that uses native Windows calls through
183 199 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
184 200 installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes`
185 201 module, which comes with Python 2.5 and greater, is required by PyReadline. It
186 202 is available for Python 2.4 at http://python.net/crew/theller/ctypes.
187 203
188 204 nose
189 205 ----
190 206
191 207 To run the IPython test suite you will need the :mod:`nose` package. Nose
192 208 provides a great way of sniffing out and running all of the IPython tests. The
193 simplest way of getting nose, is to use :command:`easy_install`::
209 simplest way of getting nose, is to use :command:`easy_install`:
210
211 .. code-block:: bash
194 212
195 $ easy_install nose
213 easy_install nose
196 214
197 Another way of getting this is to do::
215 Another way of getting this is to do:
198 216
199 $ easy_install ipython[test]
217 .. code-block:: bash
218
219 easy_install ipython[test]
200 220
201 221 For more installation options, see the `nose website
202 222 <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose
203 installed, you can run IPython's test suite using the iptest command::
223 installed, you can run IPython's test suite using the iptest command:
204 224
205 $ iptest
225 .. code-block:: bash
206 226
227 iptest
207 228
208 229 pexpect
209 230 -------
210 231
211 232 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
212 :command:`irunner` script. On Unix platforms (including OS X), just do::
233 :command:`irunner` script. On Unix platforms (including OS X), just do:
234
235 .. code-block:: bash
213 236
214 $ easy_install pexpect
237 easy_install pexpect
215 238
216 239 Windows users are out of luck as pexpect does not run there.
217 240
218 241 Dependencies for IPython.kernel (parallel computing)
219 242 ====================================================
220 243
221 244 The IPython kernel provides a nice architecture for parallel computing. The
222 245 main focus of this architecture is on interactive parallel computing. These
223 246 features require a number of additional packages:
224 247
225 248 * zope.interface (yep, we use interfaces)
226 249 * Twisted (asynchronous networking framework)
227 250 * Foolscap (a nice, secure network protocol)
228 251 * pyOpenSSL (security for network connections)
229 252
230 On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
253 On a Unix style platform (including OS X), if you want to use
254 :mod:`setuptools`, you can just do:
231 255
232 $ easy_install ipython[kernel] # the first three
233 $ easy_install ipython[security] # pyOpenSSL
256 .. code-block:: bash
257
258 easy_install ipython[kernel] # the first three
259 easy_install ipython[security] # pyOpenSSL
234 260
235 261 zope.interface and Twisted
236 262 --------------------------
237 263
238 264 Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking
239 265 related things. On Unix style platforms (including OS X), the simplest way of
240 getting the these is to use :command:`easy_install`::
266 getting the these is to use :command:`easy_install`:
267
268 .. code-block:: bash
241 269
242 $ easy_install zope.interface
243 $ easy_install Twisted
270 easy_install zope.interface
271 easy_install Twisted
244 272
245 Of course, you can also download the source tarballs from the `Twisted website
246 <twistedmatrix.org>`_ and the `zope.interface page at PyPI
273 Of course, you can also download the source tarballs from the Twisted website
274 [Twisted]_ and the `zope.interface page at PyPI
247 275 <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python
248 276 setup.py install`` if you prefer.
249 277
250 Windows is a bit different. For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website. This installer includes both zope.interface and Twisted and should just work.
278 Windows is a bit different. For zope.interface and Twisted, simply get the
279 latest binary ``.exe`` installer from the Twisted website. This installer
280 includes both zope.interface and Twisted and should just work.
251 281
252 282 Foolscap
253 283 --------
254 284
255 285 Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
256 286
257 On all platforms a simple::
287 On all platforms a simple:
288
289 .. code-block:: bash
258 290
259 $ easy_install foolscap
291 easy_install foolscap
260 292
261 293 should work. You can also download the source tarballs from the `Foolscap
262 294 website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
263 295 if you prefer.
264 296
265 297 pyOpenSSL
266 298 ---------
267 299
268 IPython requires an older version of pyOpenSSL [pyOpenSSL]_ (0.6 rather than
269 the current 0.7). There are a couple of options for getting this:
300 IPython does not work with version 0.7 of pyOpenSSL [pyOpenSSL]_. It is known
301 to work with version 0.6 and will likely work with the more recent 0.8 and 0.9
302 versions. There are a couple of options for getting this:
270 303
271 1. Most Linux distributions have packages for pyOpenSSL.
272 2. The built-in Python 2.5 on OS X 10.5 already has it installed.
273 3. There are source tarballs on the pyOpenSSL website. On Unix-like
274 platforms, these can be built using ``python seutp.py install``.
275 4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
304 1. Most Linux distributions have packages for pyOpenSSL.
305 2. The built-in Python 2.5 on OS X 10.5 already has it installed.
306 3. There are source tarballs on the pyOpenSSL website. On Unix-like
307 platforms, these can be built using ``python seutp.py install``.
308 4. There is also a binary ``.exe`` Windows installer on the
309 `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
276 310
277 311 Dependencies for IPython.frontend (the IPython GUI)
278 312 ===================================================
279 313
280 314 wxPython
281 315 --------
282 316
283 Starting with IPython 0.9, IPython has a new IPython.frontend package that has
284 a nice wxPython based IPython GUI. As you would expect, this GUI requires
285 wxPython. Most Linux distributions have wxPython packages available and the
286 built-in Python on OS X comes with wxPython preinstalled. For Windows, a
287 binary installer is available on the `wxPython website
317 Starting with IPython 0.9, IPython has a new :mod:`IPython.frontend` package
318 that has a nice wxPython based IPython GUI. As you would expect, this GUI
319 requires wxPython. Most Linux distributions have wxPython packages available
320 and the built-in Python on OS X comes with wxPython preinstalled. For Windows,
321 a binary installer is available on the `wxPython website
288 322 <http://www.wxpython.org/>`_.
289 323
290 324 .. [Twisted] Twisted matrix. http://twistedmatrix.org
291 325 .. [ZopeInterface] http://pypi.python.org/pypi/zope.interface
292 326 .. [Foolscap] Foolscap network protocol. http://foolscap.lothar.com/trac
293 327 .. [pyOpenSSL] pyOpenSSL. http://pyopenssl.sourceforge.net
294 328
@@ -1,12 +1,12 b''
1 1 ==================================
2 2 Using IPython for interactive work
3 3 ==================================
4 4
5 5 .. toctree::
6 6 :maxdepth: 2
7 7
8 8 tutorial.txt
9 9 reference.txt
10 10 shell.txt
11 extension_api.txt
11
12 12
@@ -1,1569 +1,1577 b''
1 1 =================
2 2 IPython reference
3 3 =================
4 4
5 .. warning::
6
7 As of the 0.11 version of IPython, some of the features and APIs
8 described in this section have been deprecated or are broken. Our plan
9 is to continue to support these features, but they need to be updated
10 to take advantage of recent API changes. Furthermore, this section
11 of the documentation need to be updated to reflect all of these changes.
12
5 13 .. _command_line_options:
6 14
7 15 Command-line usage
8 16 ==================
9 17
10 18 You start IPython with the command::
11 19
12 20 $ ipython [options] files
13 21
14 22 If invoked with no options, it executes all the files listed in sequence
15 23 and drops you into the interpreter while still acknowledging any options
16 24 you may have set in your ipythonrc file. This behavior is different from
17 25 standard Python, which when called as python -i will only execute one
18 26 file and ignore your configuration setup.
19 27
20 28 Please note that some of the configuration options are not available at
21 29 the command line, simply because they are not practical here. Look into
22 30 your ipythonrc configuration file for details on those. This file
23 31 typically installed in the $HOME/.ipython directory. For Windows users,
24 32 $HOME resolves to C:\\Documents and Settings\\YourUserName in most
25 33 instances. In the rest of this text, we will refer to this directory as
26 34 IPYTHONDIR.
27 35
28 36
29 37
30 38 Special Threading Options
31 39 -------------------------
32 40
33 41 Previously IPython had command line options for controlling GUI event loop
34 42 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
35 43 version 0.11, these have been deprecated. Please see the new ``%gui``
36 44 magic command or :ref:`this section <gui_support>` for details on the new
37 45 interface.
38 46
39 47 Regular Options
40 48 ---------------
41 49
42 50 After the above threading options have been given, regular options can
43 51 follow in any order. All options can be abbreviated to their shortest
44 52 non-ambiguous form and are case-sensitive. One or two dashes can be
45 53 used. Some options have an alternate short form, indicated after a ``|``.
46 54
47 55 Most options can also be set from your ipythonrc configuration file. See
48 56 the provided example for more details on what the options do. Options
49 57 given at the command line override the values set in the ipythonrc file.
50 58
51 59 All options with a [no] prepended can be specified in negated form
52 60 (-nooption instead of -option) to turn the feature off.
53 61
54 62 -help print a help message and exit.
55 63
56 64 -pylab
57 65 Deprecated. See :ref:`Matplotlib support <matplotlib_support>`
58 66 for more details.
59 67
60 68 -autocall <val>
61 69 Make IPython automatically call any callable object even if you
62 70 didn't type explicit parentheses. For example, 'str 43' becomes
63 71 'str(43)' automatically. The value can be '0' to disable the feature,
64 72 '1' for smart autocall, where it is not applied if there are no more
65 73 arguments on the line, and '2' for full autocall, where all callable
66 74 objects are automatically called (even if no arguments are
67 75 present). The default is '1'.
68 76
69 77 -[no]autoindent
70 78 Turn automatic indentation on/off.
71 79
72 80 -[no]automagic
73 81 make magic commands automatic (without needing their first character
74 82 to be %). Type %magic at the IPython prompt for more information.
75 83
76 84 -[no]autoedit_syntax
77 85 When a syntax error occurs after editing a file, automatically
78 86 open the file to the trouble causing line for convenient
79 87 fixing.
80 88
81 89 -[no]banner Print the initial information banner (default on).
82 90
83 91 -c <command>
84 92 execute the given command string. This is similar to the -c
85 93 option in the normal Python interpreter.
86 94
87 95 -cache_size, cs <n>
88 96 size of the output cache (maximum number of entries to hold in
89 97 memory). The default is 1000, you can change it permanently in your
90 98 config file. Setting it to 0 completely disables the caching system,
91 99 and the minimum value accepted is 20 (if you provide a value less than
92 100 20, it is reset to 0 and a warning is issued) This limit is defined
93 101 because otherwise you'll spend more time re-flushing a too small cache
94 102 than working.
95 103
96 104 -classic, cl
97 105 Gives IPython a similar feel to the classic Python
98 106 prompt.
99 107
100 108 -colors <scheme>
101 109 Color scheme for prompts and exception reporting. Currently
102 110 implemented: NoColor, Linux and LightBG.
103 111
104 112 -[no]color_info
105 113 IPython can display information about objects via a set of functions,
106 114 and optionally can use colors for this, syntax highlighting source
107 115 code and various other elements. However, because this information is
108 116 passed through a pager (like 'less') and many pagers get confused with
109 117 color codes, this option is off by default. You can test it and turn
110 118 it on permanently in your ipythonrc file if it works for you. As a
111 119 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
112 120 that in RedHat 7.2 doesn't.
113 121
114 122 Test it and turn it on permanently if it works with your
115 123 system. The magic function %color_info allows you to toggle this
116 124 interactively for testing.
117 125
118 126 -[no]debug
119 127 Show information about the loading process. Very useful to pin down
120 128 problems with your configuration files or to get details about
121 129 session restores.
122 130
123 131 -[no]deep_reload:
124 132 IPython can use the deep_reload module which reloads changes in
125 133 modules recursively (it replaces the reload() function, so you don't
126 134 need to change anything to use it). deep_reload() forces a full
127 135 reload of modules whose code may have changed, which the default
128 136 reload() function does not.
129 137
130 138 When deep_reload is off, IPython will use the normal reload(),
131 139 but deep_reload will still be available as dreload(). This
132 140 feature is off by default [which means that you have both
133 141 normal reload() and dreload()].
134 142
135 143 -editor <name>
136 144 Which editor to use with the %edit command. By default,
137 145 IPython will honor your EDITOR environment variable (if not
138 146 set, vi is the Unix default and notepad the Windows one).
139 147 Since this editor is invoked on the fly by IPython and is
140 148 meant for editing small code snippets, you may want to use a
141 149 small, lightweight editor here (in case your default EDITOR is
142 150 something like Emacs).
143 151
144 152 -ipythondir <name>
145 153 name of your IPython configuration directory IPYTHONDIR. This
146 154 can also be specified through the environment variable
147 155 IPYTHONDIR.
148 156
149 157 -log, l
150 158 generate a log file of all input. The file is named
151 159 ipython_log.py in your current directory (which prevents logs
152 160 from multiple IPython sessions from trampling each other). You
153 161 can use this to later restore a session by loading your
154 162 logfile as a file to be executed with option -logplay (see
155 163 below).
156 164
157 165 -logfile, lf <name> specify the name of your logfile.
158 166
159 167 -logplay, lp <name>
160 168
161 169 you can replay a previous log. For restoring a session as close as
162 170 possible to the state you left it in, use this option (don't just run
163 171 the logfile). With -logplay, IPython will try to reconstruct the
164 172 previous working environment in full, not just execute the commands in
165 173 the logfile.
166 174
167 175 When a session is restored, logging is automatically turned on
168 176 again with the name of the logfile it was invoked with (it is
169 177 read from the log header). So once you've turned logging on for
170 178 a session, you can quit IPython and reload it as many times as
171 179 you want and it will continue to log its history and restore
172 180 from the beginning every time.
173 181
174 182 Caveats: there are limitations in this option. The history
175 183 variables _i*,_* and _dh don't get restored properly. In the
176 184 future we will try to implement full session saving by writing
177 185 and retrieving a 'snapshot' of the memory state of IPython. But
178 186 our first attempts failed because of inherent limitations of
179 187 Python's Pickle module, so this may have to wait.
180 188
181 189 -[no]messages
182 190 Print messages which IPython collects about its startup
183 191 process (default on).
184 192
185 193 -[no]pdb
186 194 Automatically call the pdb debugger after every uncaught
187 195 exception. If you are used to debugging using pdb, this puts
188 196 you automatically inside of it after any call (either in
189 197 IPython or in code called by it) which triggers an exception
190 198 which goes uncaught.
191 199
192 200 -pydb
193 201 Makes IPython use the third party "pydb" package as debugger,
194 202 instead of pdb. Requires that pydb is installed.
195 203
196 204 -[no]pprint
197 205 ipython can optionally use the pprint (pretty printer) module
198 206 for displaying results. pprint tends to give a nicer display
199 207 of nested data structures. If you like it, you can turn it on
200 208 permanently in your config file (default off).
201 209
202 210 -profile, p <name>
203 211
204 212 assume that your config file is ipythonrc-<name> or
205 213 ipy_profile_<name>.py (looks in current dir first, then in
206 214 IPYTHONDIR). This is a quick way to keep and load multiple
207 215 config files for different tasks, especially if you use the
208 216 include option of config files. You can keep a basic
209 217 IPYTHONDIR/ipythonrc file and then have other 'profiles' which
210 218 include this one and load extra things for particular
211 219 tasks. For example:
212 220
213 221 1. $HOME/.ipython/ipythonrc : load basic things you always want.
214 222 2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
215 223 3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
216 224
217 225 Since it is possible to create an endless loop by having
218 226 circular file inclusions, IPython will stop if it reaches 15
219 227 recursive inclusions.
220 228
221 229 -prompt_in1, pi1 <string>
222 230
223 231 Specify the string used for input prompts. Note that if you are using
224 232 numbered prompts, the number is represented with a '\#' in the
225 233 string. Don't forget to quote strings with spaces embedded in
226 234 them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>`
227 235 discusses in detail all the available escapes to customize your
228 236 prompts.
229 237
230 238 -prompt_in2, pi2 <string>
231 239 Similar to the previous option, but used for the continuation
232 240 prompts. The special sequence '\D' is similar to '\#', but
233 241 with all digits replaced dots (so you can have your
234 242 continuation prompt aligned with your input prompt). Default:
235 243 ' .\D.:' (note three spaces at the start for alignment with
236 244 'In [\#]').
237 245
238 246 -prompt_out,po <string>
239 247 String used for output prompts, also uses numbers like
240 248 prompt_in1. Default: 'Out[\#]:'
241 249
242 250 -quick start in bare bones mode (no config file loaded).
243 251
244 252 -rcfile <name>
245 253 name of your IPython resource configuration file. Normally
246 254 IPython loads ipythonrc (from current directory) or
247 255 IPYTHONDIR/ipythonrc.
248 256
249 257 If the loading of your config file fails, IPython starts with
250 258 a bare bones configuration (no modules loaded at all).
251 259
252 260 -[no]readline
253 261 use the readline library, which is needed to support name
254 262 completion and command history, among other things. It is
255 263 enabled by default, but may cause problems for users of
256 264 X/Emacs in Python comint or shell buffers.
257 265
258 266 Note that X/Emacs 'eterm' buffers (opened with M-x term) support
259 267 IPython's readline and syntax coloring fine, only 'emacs' (M-x
260 268 shell and C-c !) buffers do not.
261 269
262 270 -screen_length, sl <n>
263 271 number of lines of your screen. This is used to control
264 272 printing of very long strings. Strings longer than this number
265 273 of lines will be sent through a pager instead of directly
266 274 printed.
267 275
268 276 The default value for this is 0, which means IPython will
269 277 auto-detect your screen size every time it needs to print certain
270 278 potentially long strings (this doesn't change the behavior of the
271 279 'print' keyword, it's only triggered internally). If for some
272 280 reason this isn't working well (it needs curses support), specify
273 281 it yourself. Otherwise don't change the default.
274 282
275 283 -separate_in, si <string>
276 284
277 285 separator before input prompts.
278 286 Default: '\n'
279 287
280 288 -separate_out, so <string>
281 289 separator before output prompts.
282 290 Default: nothing.
283 291
284 292 -separate_out2, so2
285 293 separator after output prompts.
286 294 Default: nothing.
287 295 For these three options, use the value 0 to specify no separator.
288 296
289 297 -nosep
290 298 shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
291 299 0'. Simply removes all input/output separators.
292 300
293 301 -upgrade
294 302 allows you to upgrade your IPYTHONDIR configuration when you
295 303 install a new version of IPython. Since new versions may
296 304 include new command line options or example files, this copies
297 305 updated ipythonrc-type files. However, it backs up (with a
298 306 .old extension) all files which it overwrites so that you can
299 307 merge back any customizations you might have in your personal
300 308 files. Note that you should probably use %upgrade instead,
301 309 it's a safer alternative.
302 310
303 311
304 312 -Version print version information and exit.
305 313
306 314 -wxversion <string>
307 315 Deprecated.
308 316
309 317 -xmode <modename>
310 318
311 319 Mode for exception reporting.
312 320
313 321 Valid modes: Plain, Context and Verbose.
314 322
315 323 * Plain: similar to python's normal traceback printing.
316 324 * Context: prints 5 lines of context source code around each
317 325 line in the traceback.
318 326 * Verbose: similar to Context, but additionally prints the
319 327 variables currently visible where the exception happened
320 328 (shortening their strings if too long). This can potentially be
321 329 very slow, if you happen to have a huge data structure whose
322 330 string representation is complex to compute. Your computer may
323 331 appear to freeze for a while with cpu usage at 100%. If this
324 332 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
325 333 more than once).
326 334
327 335 Interactive use
328 336 ===============
329 337
330 338 Warning: IPython relies on the existence of a global variable called
331 339 _ip which controls the shell itself. If you redefine _ip to anything,
332 340 bizarre behavior will quickly occur.
333 341
334 342 Other than the above warning, IPython is meant to work as a drop-in
335 343 replacement for the standard interactive interpreter. As such, any code
336 344 which is valid python should execute normally under IPython (cases where
337 345 this is not true should be reported as bugs). It does, however, offer
338 346 many features which are not available at a standard python prompt. What
339 347 follows is a list of these.
340 348
341 349
342 350 Caution for Windows users
343 351 -------------------------
344 352
345 353 Windows, unfortunately, uses the '\' character as a path
346 354 separator. This is a terrible choice, because '\' also represents the
347 355 escape character in most modern programming languages, including
348 356 Python. For this reason, using '/' character is recommended if you
349 357 have problems with ``\``. However, in Windows commands '/' flags
350 358 options, so you can not use it for the root directory. This means that
351 359 paths beginning at the root must be typed in a contrived manner like:
352 360 ``%copy \opt/foo/bar.txt \tmp``
353 361
354 362 .. _magic:
355 363
356 364 Magic command system
357 365 --------------------
358 366
359 367 IPython will treat any line whose first character is a % as a special
360 368 call to a 'magic' function. These allow you to control the behavior of
361 369 IPython itself, plus a lot of system-type features. They are all
362 370 prefixed with a % character, but parameters are given without
363 371 parentheses or quotes.
364 372
365 373 Example: typing '%cd mydir' (without the quotes) changes you working
366 374 directory to 'mydir', if it exists.
367 375
368 376 If you have 'automagic' enabled (in your ipythonrc file, via the command
369 377 line option -automagic or with the %automagic function), you don't need
370 378 to type in the % explicitly. IPython will scan its internal list of
371 379 magic functions and call one if it exists. With automagic on you can
372 380 then just type 'cd mydir' to go to directory 'mydir'. The automagic
373 381 system has the lowest possible precedence in name searches, so defining
374 382 an identifier with the same name as an existing magic function will
375 383 shadow it for automagic use. You can still access the shadowed magic
376 384 function by explicitly using the % character at the beginning of the line.
377 385
378 386 An example (with automagic on) should clarify all this::
379 387
380 388 In [1]: cd ipython # %cd is called by automagic
381 389
382 390 /home/fperez/ipython
383 391
384 392 In [2]: cd=1 # now cd is just a variable
385 393
386 394 In [3]: cd .. # and doesn't work as a function anymore
387 395
388 396 ------------------------------
389 397
390 398 File "<console>", line 1
391 399
392 400 cd ..
393 401
394 402 ^
395 403
396 404 SyntaxError: invalid syntax
397 405
398 406 In [4]: %cd .. # but %cd always works
399 407
400 408 /home/fperez
401 409
402 410 In [5]: del cd # if you remove the cd variable
403 411
404 412 In [6]: cd ipython # automagic can work again
405 413
406 414 /home/fperez/ipython
407 415
408 416 You can define your own magic functions to extend the system. The
409 417 following example defines a new magic command, %impall::
410 418
411 419 import IPython.ipapi
412 420
413 421 ip = IPython.ipapi.get()
414 422
415 423 def doimp(self, arg):
416 424
417 425 ip = self.api
418 426
419 427 ip.ex("import %s; reload(%s); from %s import *" % (
420 428
421 429 arg,arg,arg)
422 430
423 431 )
424 432
425 433 ip.expose_magic('impall', doimp)
426 434
427 435 You can also define your own aliased names for magic functions. In your
428 436 ipythonrc file, placing a line like::
429 437
430 438 execute __IP.magic_cl = __IP.magic_clear
431 439
432 440 will define %cl as a new name for %clear.
433 441
434 442 Type %magic for more information, including a list of all available
435 443 magic functions at any time and their docstrings. You can also type
436 444 %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
437 445 information on the '?' system) to get information about any particular
438 446 magic function you are interested in.
439 447
440 448 The API documentation for the :mod:`IPython.Magic` module contains the full
441 449 docstrings of all currently available magic commands.
442 450
443 451
444 452 Access to the standard Python help
445 453 ----------------------------------
446 454
447 455 As of Python 2.1, a help system is available with access to object docstrings
448 456 and the Python manuals. Simply type 'help' (no quotes) to access it. You can
449 457 also type help(object) to obtain information about a given object, and
450 458 help('keyword') for information on a keyword. As noted :ref:`here
451 459 <accessing_help>`, you need to properly configure your environment variable
452 460 PYTHONDOCS for this feature to work correctly.
453 461
454 462 .. _dynamic_object_info:
455 463
456 464 Dynamic object information
457 465 --------------------------
458 466
459 467 Typing ?word or word? prints detailed information about an object. If
460 468 certain strings in the object are too long (docstrings, code, etc.) they
461 469 get snipped in the center for brevity. This system gives access variable
462 470 types and values, full source code for any object (if available),
463 471 function prototypes and other useful information.
464 472
465 473 Typing ??word or word?? gives access to the full information without
466 474 snipping long strings. Long strings are sent to the screen through the
467 475 less pager if longer than the screen and printed otherwise. On systems
468 476 lacking the less command, IPython uses a very basic internal pager.
469 477
470 478 The following magic functions are particularly useful for gathering
471 479 information about your working environment. You can get more details by
472 480 typing %magic or querying them individually (use %function_name? with or
473 481 without the %), this is just a summary:
474 482
475 483 * **%pdoc <object>**: Print (or run through a pager if too long) the
476 484 docstring for an object. If the given object is a class, it will
477 485 print both the class and the constructor docstrings.
478 486 * **%pdef <object>**: Print the definition header for any callable
479 487 object. If the object is a class, print the constructor information.
480 488 * **%psource <object>**: Print (or run through a pager if too long)
481 489 the source code for an object.
482 490 * **%pfile <object>**: Show the entire source file where an object was
483 491 defined via a pager, opening it at the line where the object
484 492 definition begins.
485 493 * **%who/%whos**: These functions give information about identifiers
486 494 you have defined interactively (not things you loaded or defined
487 495 in your configuration files). %who just prints a list of
488 496 identifiers and %whos prints a table with some basic details about
489 497 each identifier.
490 498
491 499 Note that the dynamic object information functions (?/??, %pdoc, %pfile,
492 500 %pdef, %psource) give you access to documentation even on things which
493 501 are not really defined as separate identifiers. Try for example typing
494 502 {}.get? or after doing import os, type os.path.abspath??.
495 503
496 504
497 505 .. _readline:
498 506
499 507 Readline-based features
500 508 -----------------------
501 509
502 510 These features require the GNU readline library, so they won't work if
503 511 your Python installation lacks readline support. We will first describe
504 512 the default behavior IPython uses, and then how to change it to suit
505 513 your preferences.
506 514
507 515
508 516 Command line completion
509 517 +++++++++++++++++++++++
510 518
511 519 At any time, hitting TAB will complete any available python commands or
512 520 variable names, and show you a list of the possible completions if
513 521 there's no unambiguous one. It will also complete filenames in the
514 522 current directory if no python names match what you've typed so far.
515 523
516 524
517 525 Search command history
518 526 ++++++++++++++++++++++
519 527
520 528 IPython provides two ways for searching through previous input and thus
521 529 reduce the need for repetitive typing:
522 530
523 531 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
524 532 (next,down) to search through only the history items that match
525 533 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
526 534 prompt, they just behave like normal arrow keys.
527 535 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
528 536 searches your history for lines that contain what you've typed so
529 537 far, completing as much as it can.
530 538
531 539
532 540 Persistent command history across sessions
533 541 ++++++++++++++++++++++++++++++++++++++++++
534 542
535 543 IPython will save your input history when it leaves and reload it next
536 544 time you restart it. By default, the history file is named
537 545 $IPYTHONDIR/history, but if you've loaded a named profile,
538 546 '-PROFILE_NAME' is appended to the name. This allows you to keep
539 547 separate histories related to various tasks: commands related to
540 548 numerical work will not be clobbered by a system shell history, for
541 549 example.
542 550
543 551
544 552 Autoindent
545 553 ++++++++++
546 554
547 555 IPython can recognize lines ending in ':' and indent the next line,
548 556 while also un-indenting automatically after 'raise' or 'return'.
549 557
550 558 This feature uses the readline library, so it will honor your ~/.inputrc
551 559 configuration (or whatever file your INPUTRC variable points to). Adding
552 560 the following lines to your .inputrc file can make indenting/unindenting
553 561 more convenient (M-i indents, M-u unindents)::
554 562
555 563 $if Python
556 564 "\M-i": " "
557 565 "\M-u": "\d\d\d\d"
558 566 $endif
559 567
560 568 Note that there are 4 spaces between the quote marks after "M-i" above.
561 569
562 570 Warning: this feature is ON by default, but it can cause problems with
563 571 the pasting of multi-line indented code (the pasted code gets
564 572 re-indented on each line). A magic function %autoindent allows you to
565 573 toggle it on/off at runtime. You can also disable it permanently on in
566 574 your ipythonrc file (set autoindent 0).
567 575
568 576
569 577 Customizing readline behavior
570 578 +++++++++++++++++++++++++++++
571 579
572 580 All these features are based on the GNU readline library, which has an
573 581 extremely customizable interface. Normally, readline is configured via a
574 582 file which defines the behavior of the library; the details of the
575 583 syntax for this can be found in the readline documentation available
576 584 with your system or on the Internet. IPython doesn't read this file (if
577 585 it exists) directly, but it does support passing to readline valid
578 586 options via a simple interface. In brief, you can customize readline by
579 587 setting the following options in your ipythonrc configuration file (note
580 588 that these options can not be specified at the command line):
581 589
582 590 * **readline_parse_and_bind**: this option can appear as many times as
583 591 you want, each time defining a string to be executed via a
584 592 readline.parse_and_bind() command. The syntax for valid commands
585 593 of this kind can be found by reading the documentation for the GNU
586 594 readline library, as these commands are of the kind which readline
587 595 accepts in its configuration file.
588 596 * **readline_remove_delims**: a string of characters to be removed
589 597 from the default word-delimiters list used by readline, so that
590 598 completions may be performed on strings which contain them. Do not
591 599 change the default value unless you know what you're doing.
592 600 * **readline_omit__names**: when tab-completion is enabled, hitting
593 601 <tab> after a '.' in a name will complete all attributes of an
594 602 object, including all the special methods whose names include
595 603 double underscores (like __getitem__ or __class__). If you'd
596 604 rather not see these names by default, you can set this option to
597 605 1. Note that even when this option is set, you can still see those
598 606 names by explicitly typing a _ after the period and hitting <tab>:
599 607 'name._<tab>' will always complete attribute names starting with '_'.
600 608
601 609 This option is off by default so that new users see all
602 610 attributes of any objects they are dealing with.
603 611
604 612 You will find the default values along with a corresponding detailed
605 613 explanation in your ipythonrc file.
606 614
607 615
608 616 Session logging and restoring
609 617 -----------------------------
610 618
611 619 You can log all input from a session either by starting IPython with the
612 620 command line switches -log or -logfile (see :ref:`here <command_line_options>`)
613 621 or by activating the logging at any moment with the magic function %logstart.
614 622
615 623 Log files can later be reloaded with the -logplay option and IPython
616 624 will attempt to 'replay' the log by executing all the lines in it, thus
617 625 restoring the state of a previous session. This feature is not quite
618 626 perfect, but can still be useful in many cases.
619 627
620 628 The log files can also be used as a way to have a permanent record of
621 629 any code you wrote while experimenting. Log files are regular text files
622 630 which you can later open in your favorite text editor to extract code or
623 631 to 'clean them up' before using them to replay a session.
624 632
625 633 The %logstart function for activating logging in mid-session is used as
626 634 follows:
627 635
628 636 %logstart [log_name [log_mode]]
629 637
630 638 If no name is given, it defaults to a file named 'log' in your
631 639 IPYTHONDIR directory, in 'rotate' mode (see below).
632 640
633 641 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
634 642 history up to that point and then continues logging.
635 643
636 644 %logstart takes a second optional parameter: logging mode. This can be
637 645 one of (note that the modes are given unquoted):
638 646
639 647 * [over:] overwrite existing log_name.
640 648 * [backup:] rename (if exists) to log_name~ and start log_name.
641 649 * [append:] well, that says it.
642 650 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
643 651
644 652 The %logoff and %logon functions allow you to temporarily stop and
645 653 resume logging to a file which had previously been started with
646 654 %logstart. They will fail (with an explanation) if you try to use them
647 655 before logging has been started.
648 656
649 657 .. _system_shell_access:
650 658
651 659 System shell access
652 660 -------------------
653 661
654 662 Any input line beginning with a ! character is passed verbatim (minus
655 663 the !, of course) to the underlying operating system. For example,
656 664 typing !ls will run 'ls' in the current directory.
657 665
658 666 Manual capture of command output
659 667 --------------------------------
660 668
661 669 If the input line begins with two exclamation marks, !!, the command is
662 670 executed but its output is captured and returned as a python list, split
663 671 on newlines. Any output sent by the subprocess to standard error is
664 672 printed separately, so that the resulting list only captures standard
665 673 output. The !! syntax is a shorthand for the %sx magic command.
666 674
667 675 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
668 676 but allowing more fine-grained control of the capture details, and
669 677 storing the result directly into a named variable. The direct use of
670 678 %sc is now deprecated, and you should ise the ``var = !cmd`` syntax
671 679 instead.
672 680
673 681 IPython also allows you to expand the value of python variables when
674 682 making system calls. Any python variable or expression which you prepend
675 683 with $ will get expanded before the system call is made::
676 684
677 685 In [1]: pyvar='Hello world'
678 686 In [2]: !echo "A python variable: $pyvar"
679 687 A python variable: Hello world
680 688
681 689 If you want the shell to actually see a literal $, you need to type it
682 690 twice::
683 691
684 692 In [3]: !echo "A system variable: $$HOME"
685 693 A system variable: /home/fperez
686 694
687 695 You can pass arbitrary expressions, though you'll need to delimit them
688 696 with {} if there is ambiguity as to the extent of the expression::
689 697
690 698 In [5]: x=10
691 699 In [6]: y=20
692 700 In [13]: !echo $x+y
693 701 10+y
694 702 In [7]: !echo ${x+y}
695 703 30
696 704
697 705 Even object attributes can be expanded::
698 706
699 707 In [12]: !echo $sys.argv
700 708 [/home/fperez/usr/bin/ipython]
701 709
702 710
703 711 System command aliases
704 712 ----------------------
705 713
706 714 The %alias magic function and the alias option in the ipythonrc
707 715 configuration file allow you to define magic functions which are in fact
708 716 system shell commands. These aliases can have parameters.
709 717
710 718 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
711 719
712 720 Then, typing '%alias_name params' will execute the system command 'cmd
713 721 params' (from your underlying operating system).
714 722
715 723 You can also define aliases with parameters using %s specifiers (one per
716 724 parameter). The following example defines the %parts function as an
717 725 alias to the command 'echo first %s second %s' where each %s will be
718 726 replaced by a positional parameter to the call to %parts::
719 727
720 728 In [1]: alias parts echo first %s second %s
721 729 In [2]: %parts A B
722 730 first A second B
723 731 In [3]: %parts A
724 732 Incorrect number of arguments: 2 expected.
725 733 parts is an alias to: 'echo first %s second %s'
726 734
727 735 If called with no parameters, %alias prints the table of currently
728 736 defined aliases.
729 737
730 738 The %rehash/rehashx magics allow you to load your entire $PATH as
731 739 ipython aliases. See their respective docstrings (or sec. 6.2
732 740 <#sec:magic> for further details).
733 741
734 742
735 743 .. _dreload:
736 744
737 745 Recursive reload
738 746 ----------------
739 747
740 748 The dreload function does a recursive reload of a module: changes made
741 749 to the module since you imported will actually be available without
742 750 having to exit.
743 751
744 752
745 753 Verbose and colored exception traceback printouts
746 754 -------------------------------------------------
747 755
748 756 IPython provides the option to see very detailed exception tracebacks,
749 757 which can be especially useful when debugging large programs. You can
750 758 run any Python file with the %run function to benefit from these
751 759 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
752 760 be colored (if your terminal supports it) which makes them much easier
753 761 to parse visually.
754 762
755 763 See the magic xmode and colors functions for details (just type %magic).
756 764
757 765 These features are basically a terminal version of Ka-Ping Yee's cgitb
758 766 module, now part of the standard Python library.
759 767
760 768
761 769 .. _input_caching:
762 770
763 771 Input caching system
764 772 --------------------
765 773
766 774 IPython offers numbered prompts (In/Out) with input and output caching
767 775 (also referred to as 'input history'). All input is saved and can be
768 776 retrieved as variables (besides the usual arrow key recall), in
769 777 addition to the %rep magic command that brings a history entry
770 778 up for editing on the next command line.
771 779
772 780 The following GLOBAL variables always exist (so don't overwrite them!):
773 781 _i: stores previous input. _ii: next previous. _iii: next-next previous.
774 782 _ih : a list of all input _ih[n] is the input from line n and this list
775 783 is aliased to the global variable In. If you overwrite In with a
776 784 variable of your own, you can remake the assignment to the internal list
777 785 with a simple 'In=_ih'.
778 786
779 787 Additionally, global variables named _i<n> are dynamically created (<n>
780 788 being the prompt counter), such that
781 789 _i<n> == _ih[<n>] == In[<n>].
782 790
783 791 For example, what you typed at prompt 14 is available as _i14, _ih[14]
784 792 and In[14].
785 793
786 794 This allows you to easily cut and paste multi line interactive prompts
787 795 by printing them out: they print like a clean string, without prompt
788 796 characters. You can also manipulate them like regular variables (they
789 797 are strings), modify or exec them (typing 'exec _i9' will re-execute the
790 798 contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
791 799 9 through 13 and line 18).
792 800
793 801 You can also re-execute multiple lines of input easily by using the
794 802 magic %macro function (which automates the process and allows
795 803 re-execution without having to type 'exec' every time). The macro system
796 804 also allows you to re-execute previous lines which include magic
797 805 function calls (which require special processing). Type %macro? or see
798 806 sec. 6.2 <#sec:magic> for more details on the macro system.
799 807
800 808 A history function %hist allows you to see any part of your input
801 809 history by printing a range of the _i variables.
802 810
803 811 You can also search ('grep') through your history by typing
804 812 '%hist -g somestring'. This also searches through the so called *shadow history*,
805 813 which remembers all the commands (apart from multiline code blocks)
806 814 you have ever entered. Handy for searching for svn/bzr URL's, IP adrresses
807 815 etc. You can bring shadow history entries listed by '%hist -g' up for editing
808 816 (or re-execution by just pressing ENTER) with %rep command. Shadow history
809 817 entries are not available as _iNUMBER variables, and they are identified by
810 818 the '0' prefix in %hist -g output. That is, history entry 12 is a normal
811 819 history entry, but 0231 is a shadow history entry.
812 820
813 821 Shadow history was added because the readline history is inherently very
814 822 unsafe - if you have multiple IPython sessions open, the last session
815 823 to close will overwrite the history of previountly closed session. Likewise,
816 824 if a crash occurs, history is never saved, whereas shadow history entries
817 825 are added after entering every command (so a command executed
818 826 in another IPython session is immediately available in other IPython
819 827 sessions that are open).
820 828
821 829 To conserve space, a command can exist in shadow history only once - it doesn't
822 830 make sense to store a common line like "cd .." a thousand times. The idea is
823 831 mainly to provide a reliable place where valuable, hard-to-remember commands can
824 832 always be retrieved, as opposed to providing an exact sequence of commands
825 833 you have entered in actual order.
826 834
827 835 Because shadow history has all the commands you have ever executed,
828 836 time taken by %hist -g will increase oven time. If it ever starts to take
829 837 too long (or it ends up containing sensitive information like passwords),
830 838 clear the shadow history by `%clear shadow_nuke`.
831 839
832 840 Time taken to add entries to shadow history should be negligible, but
833 841 in any case, if you start noticing performance degradation after using
834 842 IPython for a long time (or running a script that floods the shadow history!),
835 843 you can 'compress' the shadow history by executing
836 844 `%clear shadow_compress`. In practice, this should never be necessary
837 845 in normal use.
838 846
839 847 .. _output_caching:
840 848
841 849 Output caching system
842 850 ---------------------
843 851
844 852 For output that is returned from actions, a system similar to the input
845 853 cache exists but using _ instead of _i. Only actions that produce a
846 854 result (NOT assignments, for example) are cached. If you are familiar
847 855 with Mathematica, IPython's _ variables behave exactly like
848 856 Mathematica's % variables.
849 857
850 858 The following GLOBAL variables always exist (so don't overwrite them!):
851 859
852 860 * [_] (a single underscore) : stores previous output, like Python's
853 861 default interpreter.
854 862 * [__] (two underscores): next previous.
855 863 * [___] (three underscores): next-next previous.
856 864
857 865 Additionally, global variables named _<n> are dynamically created (<n>
858 866 being the prompt counter), such that the result of output <n> is always
859 867 available as _<n> (don't use the angle brackets, just the number, e.g.
860 868 _21).
861 869
862 870 These global variables are all stored in a global dictionary (not a
863 871 list, since it only has entries for lines which returned a result)
864 872 available under the names _oh and Out (similar to _ih and In). So the
865 873 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
866 874 accidentally overwrite the Out variable you can recover it by typing
867 875 'Out=_oh' at the prompt.
868 876
869 877 This system obviously can potentially put heavy memory demands on your
870 878 system, since it prevents Python's garbage collector from removing any
871 879 previously computed results. You can control how many results are kept
872 880 in memory with the option (at the command line or in your ipythonrc
873 881 file) cache_size. If you set it to 0, the whole system is completely
874 882 disabled and the prompts revert to the classic '>>>' of normal Python.
875 883
876 884
877 885 Directory history
878 886 -----------------
879 887
880 888 Your history of visited directories is kept in the global list _dh, and
881 889 the magic %cd command can be used to go to any entry in that list. The
882 890 %dhist command allows you to view this history. Do ``cd -<TAB`` to
883 891 conventiently view the directory history.
884 892
885 893
886 894 Automatic parentheses and quotes
887 895 --------------------------------
888 896
889 897 These features were adapted from Nathan Gray's LazyPython. They are
890 898 meant to allow less typing for common situations.
891 899
892 900
893 901 Automatic parentheses
894 902 ---------------------
895 903
896 904 Callable objects (i.e. functions, methods, etc) can be invoked like this
897 905 (notice the commas between the arguments)::
898 906
899 907 >>> callable_ob arg1, arg2, arg3
900 908
901 909 and the input will be translated to this::
902 910
903 911 -> callable_ob(arg1, arg2, arg3)
904 912
905 913 You can force automatic parentheses by using '/' as the first character
906 914 of a line. For example::
907 915
908 916 >>> /globals # becomes 'globals()'
909 917
910 918 Note that the '/' MUST be the first character on the line! This won't work::
911 919
912 920 >>> print /globals # syntax error
913 921
914 922 In most cases the automatic algorithm should work, so you should rarely
915 923 need to explicitly invoke /. One notable exception is if you are trying
916 924 to call a function with a list of tuples as arguments (the parenthesis
917 925 will confuse IPython)::
918 926
919 927 In [1]: zip (1,2,3),(4,5,6) # won't work
920 928
921 929 but this will work::
922 930
923 931 In [2]: /zip (1,2,3),(4,5,6)
924 932 ---> zip ((1,2,3),(4,5,6))
925 933 Out[2]= [(1, 4), (2, 5), (3, 6)]
926 934
927 935 IPython tells you that it has altered your command line by displaying
928 936 the new command line preceded by ->. e.g.::
929 937
930 938 In [18]: callable list
931 939 ----> callable (list)
932 940
933 941
934 942 Automatic quoting
935 943 -----------------
936 944
937 945 You can force automatic quoting of a function's arguments by using ','
938 946 or ';' as the first character of a line. For example::
939 947
940 948 >>> ,my_function /home/me # becomes my_function("/home/me")
941 949
942 950 If you use ';' instead, the whole argument is quoted as a single string
943 951 (while ',' splits on whitespace)::
944 952
945 953 >>> ,my_function a b c # becomes my_function("a","b","c")
946 954
947 955 >>> ;my_function a b c # becomes my_function("a b c")
948 956
949 957 Note that the ',' or ';' MUST be the first character on the line! This
950 958 won't work::
951 959
952 960 >>> x = ,my_function /home/me # syntax error
953 961
954 962 IPython as your default Python environment
955 963 ==========================================
956 964
957 965 Python honors the environment variable PYTHONSTARTUP and will execute at
958 966 startup the file referenced by this variable. If you put at the end of
959 967 this file the following two lines of code::
960 968
961 969 import IPython
962 970 IPython.Shell.IPShell().mainloop(sys_exit=1)
963 971
964 972 then IPython will be your working environment anytime you start Python.
965 973 The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
966 974 it finishes, otherwise you'll be back at the normal Python '>>>'
967 975 prompt.
968 976
969 977 This is probably useful to developers who manage multiple Python
970 978 versions and don't want to have correspondingly multiple IPython
971 979 versions. Note that in this mode, there is no way to pass IPython any
972 980 command-line options, as those are trapped first by Python itself.
973 981
974 982 .. _Embedding:
975 983
976 984 Embedding IPython
977 985 =================
978 986
979 987 It is possible to start an IPython instance inside your own Python
980 988 programs. This allows you to evaluate dynamically the state of your
981 989 code, operate with your variables, analyze them, etc. Note however that
982 990 any changes you make to values while in the shell do not propagate back
983 991 to the running code, so it is safe to modify your values because you
984 992 won't break your code in bizarre ways by doing so.
985 993
986 994 This feature allows you to easily have a fully functional python
987 995 environment for doing object introspection anywhere in your code with a
988 996 simple function call. In some cases a simple print statement is enough,
989 997 but if you need to do more detailed analysis of a code fragment this
990 998 feature can be very valuable.
991 999
992 1000 It can also be useful in scientific computing situations where it is
993 1001 common to need to do some automatic, computationally intensive part and
994 1002 then stop to look at data, plots, etc.
995 1003 Opening an IPython instance will give you full access to your data and
996 1004 functions, and you can resume program execution once you are done with
997 1005 the interactive part (perhaps to stop again later, as many times as
998 1006 needed).
999 1007
1000 1008 The following code snippet is the bare minimum you need to include in
1001 1009 your Python programs for this to work (detailed examples follow later)::
1002 1010
1003 1011 from IPython.Shell import IPShellEmbed
1004 1012
1005 1013 ipshell = IPShellEmbed()
1006 1014
1007 1015 ipshell() # this call anywhere in your program will start IPython
1008 1016
1009 1017 You can run embedded instances even in code which is itself being run at
1010 1018 the IPython interactive prompt with '%run <filename>'. Since it's easy
1011 1019 to get lost as to where you are (in your top-level IPython or in your
1012 1020 embedded one), it's a good idea in such cases to set the in/out prompts
1013 1021 to something different for the embedded instances. The code examples
1014 1022 below illustrate this.
1015 1023
1016 1024 You can also have multiple IPython instances in your program and open
1017 1025 them separately, for example with different options for data
1018 1026 presentation. If you close and open the same instance multiple times,
1019 1027 its prompt counters simply continue from each execution to the next.
1020 1028
1021 1029 Please look at the docstrings in the Shell.py module for more details on
1022 1030 the use of this system.
1023 1031
1024 1032 The following sample file illustrating how to use the embedding
1025 1033 functionality is provided in the examples directory as example-embed.py.
1026 1034 It should be fairly self-explanatory::
1027 1035
1028 1036
1029 1037 #!/usr/bin/env python
1030 1038
1031 1039 """An example of how to embed an IPython shell into a running program.
1032 1040
1033 1041 Please see the documentation in the IPython.Shell module for more details.
1034 1042
1035 1043 The accompanying file example-embed-short.py has quick code fragments for
1036 1044 embedding which you can cut and paste in your code once you understand how
1037 1045 things work.
1038 1046
1039 1047 The code in this file is deliberately extra-verbose, meant for learning."""
1040 1048
1041 1049 # The basics to get you going:
1042 1050
1043 1051 # IPython sets the __IPYTHON__ variable so you can know if you have nested
1044 1052 # copies running.
1045 1053
1046 1054 # Try running this code both at the command line and from inside IPython (with
1047 1055 # %run example-embed.py)
1048 1056 try:
1049 1057 __IPYTHON__
1050 1058 except NameError:
1051 1059 nested = 0
1052 1060 args = ['']
1053 1061 else:
1054 1062 print "Running nested copies of IPython."
1055 1063 print "The prompts for the nested copy have been modified"
1056 1064 nested = 1
1057 1065 # what the embedded instance will see as sys.argv:
1058 1066 args = ['-pi1','In <\\#>: ','-pi2',' .\\D.: ',
1059 1067 '-po','Out<\\#>: ','-nosep']
1060 1068
1061 1069 # First import the embeddable shell class
1062 1070 from IPython.Shell import IPShellEmbed
1063 1071
1064 1072 # Now create an instance of the embeddable shell. The first argument is a
1065 1073 # string with options exactly as you would type them if you were starting
1066 1074 # IPython at the system command line. Any parameters you want to define for
1067 1075 # configuration can thus be specified here.
1068 1076 ipshell = IPShellEmbed(args,
1069 1077 banner = 'Dropping into IPython',
1070 1078 exit_msg = 'Leaving Interpreter, back to program.')
1071 1079
1072 1080 # Make a second instance, you can have as many as you want.
1073 1081 if nested:
1074 1082 args[1] = 'In2<\\#>'
1075 1083 else:
1076 1084 args = ['-pi1','In2<\\#>: ','-pi2',' .\\D.: ',
1077 1085 '-po','Out<\\#>: ','-nosep']
1078 1086 ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
1079 1087
1080 1088 print '\nHello. This is printed from the main controller program.\n'
1081 1089
1082 1090 # You can then call ipshell() anywhere you need it (with an optional
1083 1091 # message):
1084 1092 ipshell('***Called from top level. '
1085 1093 'Hit Ctrl-D to exit interpreter and continue program.\n'
1086 1094 'Note that if you use %kill_embedded, you can fully deactivate\n'
1087 1095 'This embedded instance so it will never turn on again')
1088 1096
1089 1097 print '\nBack in caller program, moving along...\n'
1090 1098
1091 1099 #---------------------------------------------------------------------------
1092 1100 # More details:
1093 1101
1094 1102 # IPShellEmbed instances don't print the standard system banner and
1095 1103 # messages. The IPython banner (which actually may contain initialization
1096 1104 # messages) is available as <instance>.IP.BANNER in case you want it.
1097 1105
1098 1106 # IPShellEmbed instances print the following information everytime they
1099 1107 # start:
1100 1108
1101 1109 # - A global startup banner.
1102 1110
1103 1111 # - A call-specific header string, which you can use to indicate where in the
1104 1112 # execution flow the shell is starting.
1105 1113
1106 1114 # They also print an exit message every time they exit.
1107 1115
1108 1116 # Both the startup banner and the exit message default to None, and can be set
1109 1117 # either at the instance constructor or at any other time with the
1110 1118 # set_banner() and set_exit_msg() methods.
1111 1119
1112 1120 # The shell instance can be also put in 'dummy' mode globally or on a per-call
1113 1121 # basis. This gives you fine control for debugging without having to change
1114 1122 # code all over the place.
1115 1123
1116 1124 # The code below illustrates all this.
1117 1125
1118 1126
1119 1127 # This is how the global banner and exit_msg can be reset at any point
1120 1128 ipshell.set_banner('Entering interpreter - New Banner')
1121 1129 ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
1122 1130
1123 1131 def foo(m):
1124 1132 s = 'spam'
1125 1133 ipshell('***In foo(). Try @whos, or print s or m:')
1126 1134 print 'foo says m = ',m
1127 1135
1128 1136 def bar(n):
1129 1137 s = 'eggs'
1130 1138 ipshell('***In bar(). Try @whos, or print s or n:')
1131 1139 print 'bar says n = ',n
1132 1140
1133 1141 # Some calls to the above functions which will trigger IPython:
1134 1142 print 'Main program calling foo("eggs")\n'
1135 1143 foo('eggs')
1136 1144
1137 1145 # The shell can be put in 'dummy' mode where calls to it silently return. This
1138 1146 # allows you, for example, to globally turn off debugging for a program with a
1139 1147 # single call.
1140 1148 ipshell.set_dummy_mode(1)
1141 1149 print '\nTrying to call IPython which is now "dummy":'
1142 1150 ipshell()
1143 1151 print 'Nothing happened...'
1144 1152 # The global 'dummy' mode can still be overridden for a single call
1145 1153 print '\nOverriding dummy mode manually:'
1146 1154 ipshell(dummy=0)
1147 1155
1148 1156 # Reactivate the IPython shell
1149 1157 ipshell.set_dummy_mode(0)
1150 1158
1151 1159 print 'You can even have multiple embedded instances:'
1152 1160 ipshell2()
1153 1161
1154 1162 print '\nMain program calling bar("spam")\n'
1155 1163 bar('spam')
1156 1164
1157 1165 print 'Main program finished. Bye!'
1158 1166
1159 1167 #********************** End of file <example-embed.py> ***********************
1160 1168
1161 1169 Once you understand how the system functions, you can use the following
1162 1170 code fragments in your programs which are ready for cut and paste::
1163 1171
1164 1172
1165 1173 """Quick code snippets for embedding IPython into other programs.
1166 1174
1167 1175 See example-embed.py for full details, this file has the bare minimum code for
1168 1176 cut and paste use once you understand how to use the system."""
1169 1177
1170 1178 #---------------------------------------------------------------------------
1171 1179 # This code loads IPython but modifies a few things if it detects it's running
1172 1180 # embedded in another IPython session (helps avoid confusion)
1173 1181
1174 1182 try:
1175 1183 __IPYTHON__
1176 1184 except NameError:
1177 1185 argv = ['']
1178 1186 banner = exit_msg = ''
1179 1187 else:
1180 1188 # Command-line options for IPython (a list like sys.argv)
1181 1189 argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:']
1182 1190 banner = '*** Nested interpreter ***'
1183 1191 exit_msg = '*** Back in main IPython ***'
1184 1192
1185 1193 # First import the embeddable shell class
1186 1194 from IPython.Shell import IPShellEmbed
1187 1195 # Now create the IPython shell instance. Put ipshell() anywhere in your code
1188 1196 # where you want it to open.
1189 1197 ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
1190 1198
1191 1199 #---------------------------------------------------------------------------
1192 1200 # This code will load an embeddable IPython shell always with no changes for
1193 1201 # nested embededings.
1194 1202
1195 1203 from IPython.Shell import IPShellEmbed
1196 1204 ipshell = IPShellEmbed()
1197 1205 # Now ipshell() will open IPython anywhere in the code.
1198 1206
1199 1207 #---------------------------------------------------------------------------
1200 1208 # This code loads an embeddable shell only if NOT running inside
1201 1209 # IPython. Inside IPython, the embeddable shell variable ipshell is just a
1202 1210 # dummy function.
1203 1211
1204 1212 try:
1205 1213 __IPYTHON__
1206 1214 except NameError:
1207 1215 from IPython.Shell import IPShellEmbed
1208 1216 ipshell = IPShellEmbed()
1209 1217 # Now ipshell() will open IPython anywhere in the code
1210 1218 else:
1211 1219 # Define a dummy ipshell() so the same code doesn't crash inside an
1212 1220 # interactive IPython
1213 1221 def ipshell(): pass
1214 1222
1215 1223 #******************* End of file <example-embed-short.py> ********************
1216 1224
1217 1225 Using the Python debugger (pdb)
1218 1226 ===============================
1219 1227
1220 1228 Running entire programs via pdb
1221 1229 -------------------------------
1222 1230
1223 1231 pdb, the Python debugger, is a powerful interactive debugger which
1224 1232 allows you to step through code, set breakpoints, watch variables,
1225 1233 etc. IPython makes it very easy to start any script under the control
1226 1234 of pdb, regardless of whether you have wrapped it into a 'main()'
1227 1235 function or not. For this, simply type '%run -d myscript' at an
1228 1236 IPython prompt. See the %run command's documentation (via '%run?' or
1229 1237 in Sec. magic_ for more details, including how to control where pdb
1230 1238 will stop execution first.
1231 1239
1232 1240 For more information on the use of the pdb debugger, read the included
1233 1241 pdb.doc file (part of the standard Python distribution). On a stock
1234 1242 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
1235 1243 easiest way to read it is by using the help() function of the pdb module
1236 1244 as follows (in an IPython prompt):
1237 1245
1238 1246 In [1]: import pdb
1239 1247 In [2]: pdb.help()
1240 1248
1241 1249 This will load the pdb.doc document in a file viewer for you automatically.
1242 1250
1243 1251
1244 1252 Automatic invocation of pdb on exceptions
1245 1253 -----------------------------------------
1246 1254
1247 1255 IPython, if started with the -pdb option (or if the option is set in
1248 1256 your rc file) can call the Python pdb debugger every time your code
1249 1257 triggers an uncaught exception. This feature
1250 1258 can also be toggled at any time with the %pdb magic command. This can be
1251 1259 extremely useful in order to find the origin of subtle bugs, because pdb
1252 1260 opens up at the point in your code which triggered the exception, and
1253 1261 while your program is at this point 'dead', all the data is still
1254 1262 available and you can walk up and down the stack frame and understand
1255 1263 the origin of the problem.
1256 1264
1257 1265 Furthermore, you can use these debugging facilities both with the
1258 1266 embedded IPython mode and without IPython at all. For an embedded shell
1259 1267 (see sec. Embedding_), simply call the constructor with
1260 1268 '-pdb' in the argument string and automatically pdb will be called if an
1261 1269 uncaught exception is triggered by your code.
1262 1270
1263 1271 For stand-alone use of the feature in your programs which do not use
1264 1272 IPython at all, put the following lines toward the top of your 'main'
1265 1273 routine::
1266 1274
1267 1275 import sys
1268 1276 from IPython.core import ultratb
1269 1277 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
1270 1278 color_scheme='Linux', call_pdb=1)
1271 1279
1272 1280 The mode keyword can be either 'Verbose' or 'Plain', giving either very
1273 1281 detailed or normal tracebacks respectively. The color_scheme keyword can
1274 1282 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
1275 1283 options which can be set in IPython with -colors and -xmode.
1276 1284
1277 1285 This will give any of your programs detailed, colored tracebacks with
1278 1286 automatic invocation of pdb.
1279 1287
1280 1288
1281 1289 Extensions for syntax processing
1282 1290 ================================
1283 1291
1284 1292 This isn't for the faint of heart, because the potential for breaking
1285 1293 things is quite high. But it can be a very powerful and useful feature.
1286 1294 In a nutshell, you can redefine the way IPython processes the user input
1287 1295 line to accept new, special extensions to the syntax without needing to
1288 1296 change any of IPython's own code.
1289 1297
1290 1298 In the IPython/extensions directory you will find some examples
1291 1299 supplied, which we will briefly describe now. These can be used 'as is'
1292 1300 (and both provide very useful functionality), or you can use them as a
1293 1301 starting point for writing your own extensions.
1294 1302
1295 1303
1296 1304 Pasting of code starting with '>>> ' or '... '
1297 1305 ----------------------------------------------
1298 1306
1299 1307 In the python tutorial it is common to find code examples which have
1300 1308 been taken from real python sessions. The problem with those is that all
1301 1309 the lines begin with either '>>> ' or '... ', which makes it impossible
1302 1310 to paste them all at once. One must instead do a line by line manual
1303 1311 copying, carefully removing the leading extraneous characters.
1304 1312
1305 1313 This extension identifies those starting characters and removes them
1306 1314 from the input automatically, so that one can paste multi-line examples
1307 1315 directly into IPython, saving a lot of time. Please look at the file
1308 1316 InterpreterPasteInput.py in the IPython/extensions directory for details
1309 1317 on how this is done.
1310 1318
1311 1319 IPython comes with a special profile enabling this feature, called
1312 1320 tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
1313 1321 will be available. In a normal IPython session you can activate the
1314 1322 feature by importing the corresponding module with:
1315 1323 In [1]: import IPython.extensions.InterpreterPasteInput
1316 1324
1317 1325 The following is a 'screenshot' of how things work when this extension
1318 1326 is on, copying an example from the standard tutorial::
1319 1327
1320 1328 IPython profile: tutorial
1321 1329
1322 1330 *** Pasting of code with ">>>" or "..." has been enabled.
1323 1331
1324 1332 In [1]: >>> def fib2(n): # return Fibonacci series up to n
1325 1333 ...: ... """Return a list containing the Fibonacci series up to
1326 1334 n."""
1327 1335 ...: ... result = []
1328 1336 ...: ... a, b = 0, 1
1329 1337 ...: ... while b < n:
1330 1338 ...: ... result.append(b) # see below
1331 1339 ...: ... a, b = b, a+b
1332 1340 ...: ... return result
1333 1341 ...:
1334 1342
1335 1343 In [2]: fib2(10)
1336 1344 Out[2]: [1, 1, 2, 3, 5, 8]
1337 1345
1338 1346 Note that as currently written, this extension does not recognize
1339 1347 IPython's prompts for pasting. Those are more complicated, since the
1340 1348 user can change them very easily, they involve numbers and can vary in
1341 1349 length. One could however extract all the relevant information from the
1342 1350 IPython instance and build an appropriate regular expression. This is
1343 1351 left as an exercise for the reader.
1344 1352
1345 1353
1346 1354 Input of physical quantities with units
1347 1355 ---------------------------------------
1348 1356
1349 1357 The module PhysicalQInput allows a simplified form of input for physical
1350 1358 quantities with units. This file is meant to be used in conjunction with
1351 1359 the PhysicalQInteractive module (in the same directory) and
1352 1360 Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
1353 1361 (http://dirac.cnrs-orleans.fr/ScientificPython/).
1354 1362
1355 1363 The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
1356 1364 but these must be declared as instances of a class. For example, to
1357 1365 define v as a velocity of 3 m/s, normally you would write::
1358 1366
1359 1367 In [1]: v = PhysicalQuantity(3,'m/s')
1360 1368
1361 1369 Using the PhysicalQ_Input extension this can be input instead as:
1362 1370 In [1]: v = 3 m/s
1363 1371 which is much more convenient for interactive use (even though it is
1364 1372 blatantly invalid Python syntax).
1365 1373
1366 1374 The physics profile supplied with IPython (enabled via 'ipython -p
1367 1375 physics') uses these extensions, which you can also activate with:
1368 1376
1369 1377 from math import * # math MUST be imported BEFORE PhysicalQInteractive
1370 1378 from IPython.extensions.PhysicalQInteractive import *
1371 1379 import IPython.extensions.PhysicalQInput
1372 1380
1373 1381 .. _gui_support:
1374 1382
1375 1383 GUI event loop support support
1376 1384 ==============================
1377 1385
1378 1386 .. versionadded:: 0.11
1379 1387 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
1380 1388
1381 1389 IPython has excellent support for working interactively with Graphical User
1382 1390 Interface (GUI) toolkits, such as wxPython, PyQt4, PyGTK and Tk. This is
1383 1391 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
1384 1392 is extremely robust compared to our previous threaded based version. The
1385 1393 advantages of this are:
1386 1394
1387 1395 * GUIs can be enabled and disabled dynamically at runtime.
1388 1396 * The active GUI can be switched dynamically at runtime.
1389 1397 * In some cases, multiple GUIs can run simultaneously with no problems.
1390 1398 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
1391 1399 all of these things.
1392 1400
1393 1401 For users, enabling GUI event loop integration is simple. You simple use the
1394 1402 ``%gui`` magic as follows::
1395 1403
1396 1404 %gui [-a] [GUINAME]
1397 1405
1398 1406 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
1399 1407 arguments are ``wx``, ``qt4``, ``gtk`` and ``tk``. The ``-a`` option will
1400 1408 create and return a running application object for the selected GUI toolkit.
1401 1409
1402 1410 Thus, to use wxPython interactively and create a running :class:`wx.App`
1403 1411 object, do::
1404 1412
1405 1413 %gui -a wx
1406 1414
1407 1415 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
1408 1416 see :ref:`this section <matplotlib_support>`.
1409 1417
1410 1418 For developers that want to use IPython's GUI event loop integration in
1411 1419 the form of a library, these capabilities are exposed in library form
1412 1420 in the :mod:`IPython.lib.inputhook`. Interested developers should see the
1413 1421 module docstrings for more information, but there are a few points that
1414 1422 should be mentioned here.
1415 1423
1416 1424 First, the ``PyOSInputHook`` approach only works in command line settings
1417 1425 where readline is activated.
1418 1426
1419 1427 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1420 1428 *not* start its event loop. Instead all of this is handled by the
1421 1429 ``PyOSInputHook``. This means that applications that are meant to be used both
1422 1430 in IPython and as standalone apps need to have special code to detects how the
1423 1431 application is being run. We highly recommend using IPython's
1424 1432 :func:`appstart_` functions for this. Here is a simple example that shows the
1425 1433 recommended code that should be at the bottom of a wxPython using GUI
1426 1434 application::
1427 1435
1428 1436 try:
1429 1437 from IPython import appstart_wx
1430 1438 appstart_wx(app)
1431 1439 except ImportError:
1432 1440 app.MainLoop()
1433 1441
1434 1442 This pattern should be used instead of the simple ``app.MainLoop()`` code
1435 1443 that a standalone wxPython application would have.
1436 1444
1437 1445 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1438 1446 them with no-ops) the event loops. This is done to allow applications that
1439 1447 actually need to run the real event loops to do so. This is often needed to
1440 1448 process pending events at critical points.
1441 1449
1442 1450 Finally, we also have a number of examples in our source directory
1443 1451 :file:`docs/examples/lib` that demonstrate these capabilities.
1444 1452
1445 1453 .. _matplotlib_support:
1446 1454
1447 1455 Plotting with matplotlib
1448 1456 ========================
1449 1457
1450 1458
1451 1459 `Matplotlib`_ provides high quality 2D and
1452 1460 3D plotting for Python. Matplotlib can produce plots on screen using a variety
1453 1461 of GUI toolkits, including Tk, PyGTK, PyQt4 and wxPython. It also provides a
1454 1462 number of commands useful for scientific computing, all with a syntax
1455 1463 compatible with that of the popular Matlab program.
1456 1464
1457 1465 Many IPython users have come to rely on IPython's ``-pylab`` mode which
1458 1466 automates the integration of Matplotlib with IPython. We are still in the
1459 1467 process of working with the Matplotlib developers to finalize the new pylab
1460 1468 API, but for now you can use Matplotlib interactively using the following
1461 1469 commands::
1462 1470
1463 1471 %gui -a wx
1464 1472 import matplotlib
1465 1473 matplotlib.use('wxagg')
1466 1474 from matplotlib import pylab
1467 1475 pylab.interactive(True)
1468 1476
1469 1477 All of this will soon be automated as Matplotlib beings to include
1470 1478 new logic that uses our new GUI support.
1471 1479
1472 1480 .. _interactive_demos:
1473 1481
1474 1482 Interactive demos with IPython
1475 1483 ==============================
1476 1484
1477 1485 IPython ships with a basic system for running scripts interactively in
1478 1486 sections, useful when presenting code to audiences. A few tags embedded
1479 1487 in comments (so that the script remains valid Python code) divide a file
1480 1488 into separate blocks, and the demo can be run one block at a time, with
1481 1489 IPython printing (with syntax highlighting) the block before executing
1482 1490 it, and returning to the interactive prompt after each block. The
1483 1491 interactive namespace is updated after each block is run with the
1484 1492 contents of the demo's namespace.
1485 1493
1486 1494 This allows you to show a piece of code, run it and then execute
1487 1495 interactively commands based on the variables just created. Once you
1488 1496 want to continue, you simply execute the next block of the demo. The
1489 1497 following listing shows the markup necessary for dividing a script into
1490 1498 sections for execution as a demo::
1491 1499
1492 1500
1493 1501 """A simple interactive demo to illustrate the use of IPython's Demo class.
1494 1502
1495 1503 Any python script can be run as a demo, but that does little more than showing
1496 1504 it on-screen, syntax-highlighted in one shot. If you add a little simple
1497 1505 markup, you can stop at specified intervals and return to the ipython prompt,
1498 1506 resuming execution later.
1499 1507 """
1500 1508
1501 1509 print 'Hello, welcome to an interactive IPython demo.'
1502 1510 print 'Executing this block should require confirmation before proceeding,'
1503 1511 print 'unless auto_all has been set to true in the demo object'
1504 1512
1505 1513 # The mark below defines a block boundary, which is a point where IPython will
1506 1514 # stop execution and return to the interactive prompt.
1507 1515 # Note that in actual interactive execution,
1508 1516 # <demo> --- stop ---
1509 1517
1510 1518 x = 1
1511 1519 y = 2
1512 1520
1513 1521 # <demo> --- stop ---
1514 1522
1515 1523 # the mark below makes this block as silent
1516 1524 # <demo> silent
1517 1525
1518 1526 print 'This is a silent block, which gets executed but not printed.'
1519 1527
1520 1528 # <demo> --- stop ---
1521 1529 # <demo> auto
1522 1530 print 'This is an automatic block.'
1523 1531 print 'It is executed without asking for confirmation, but printed.'
1524 1532 z = x+y
1525 1533
1526 1534 print 'z=',x
1527 1535
1528 1536 # <demo> --- stop ---
1529 1537 # This is just another normal block.
1530 1538 print 'z is now:', z
1531 1539
1532 1540 print 'bye!'
1533 1541
1534 1542 In order to run a file as a demo, you must first make a Demo object out
1535 1543 of it. If the file is named myscript.py, the following code will make a
1536 1544 demo::
1537 1545
1538 1546 from IPython.demo import Demo
1539 1547
1540 1548 mydemo = Demo('myscript.py')
1541 1549
1542 1550 This creates the mydemo object, whose blocks you run one at a time by
1543 1551 simply calling the object with no arguments. If you have autocall active
1544 1552 in IPython (the default), all you need to do is type::
1545 1553
1546 1554 mydemo
1547 1555
1548 1556 and IPython will call it, executing each block. Demo objects can be
1549 1557 restarted, you can move forward or back skipping blocks, re-execute the
1550 1558 last block, etc. Simply use the Tab key on a demo object to see its
1551 1559 methods, and call '?' on them to see their docstrings for more usage
1552 1560 details. In addition, the demo module itself contains a comprehensive
1553 1561 docstring, which you can access via::
1554 1562
1555 1563 from IPython import demo
1556 1564
1557 1565 demo?
1558 1566
1559 1567 Limitations: It is important to note that these demos are limited to
1560 1568 fairly simple uses. In particular, you can not put division marks in
1561 1569 indented code (loops, if statements, function definitions, etc.)
1562 1570 Supporting something like this would basically require tracking the
1563 1571 internal execution state of the Python interpreter, so only top-level
1564 1572 divisions are allowed. If you want to be able to open an IPython
1565 1573 instance at an arbitrary point in a program, you can use IPython's
1566 1574 embedding facilities, described in detail in Sec. 9
1567 1575
1568 1576 .. [Matplotlib] Matplotlib. http://matplotlib.sourceforge.net
1569 1577
@@ -1,285 +1,293 b''
1 1 .. _ipython_as_shell:
2 2
3 3 =========================
4 4 IPython as a system shell
5 5 =========================
6 6
7 .. warning::
8
9 As of the 0.11 version of IPython, some of the features and APIs
10 described in this section have been deprecated or are broken. Our plan
11 is to continue to support these features, but they need to be updated
12 to take advantage of recent API changes. Furthermore, this section
13 of the documentation need to be updated to reflect all of these changes.
14
7 15 Overview
8 16 ========
9 17
10 18 The 'sh' profile optimizes IPython for system shell usage. Apart from
11 19 certain job control functionality that is present in unix (ctrl+z does
12 20 "suspend"), the sh profile should provide you with most of the
13 21 functionality you use daily in system shell, and more. Invoke IPython
14 22 in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching
15 23 the "pysh" shortcut in start menu.
16 24
17 25 If you want to use the features of sh profile as your defaults (which
18 26 might be a good idea if you use other profiles a lot of the time but
19 27 still want the convenience of sh profile), add ``import ipy_profile_sh``
20 28 to your ~/.ipython/ipy_user_conf.py.
21 29
22 30 The 'sh' profile is different from the default profile in that:
23 31
24 32 * Prompt shows the current directory
25 33 * Spacing between prompts and input is more compact (no padding with
26 34 empty lines). The startup banner is more compact as well.
27 35 * System commands are directly available (in alias table) without
28 36 requesting %rehashx - however, if you install new programs along
29 37 your PATH, you might want to run %rehashx to update the persistent
30 38 alias table
31 39 * Macros are stored in raw format by default. That is, instead of
32 40 '_ip.system("cat foo"), the macro will contain text 'cat foo')
33 41 * Autocall is in full mode
34 42 * Calling "up" does "cd .."
35 43
36 44 The 'sh' profile is different from the now-obsolete (and unavailable)
37 45 'pysh' profile in that:
38 46
39 47 * '$$var = command' and '$var = command' syntax is not supported
40 48 * anymore. Use 'var = !command' instead (incidentally, this is
41 49 * available in all IPython profiles). Note that !!command *will*
42 50 * work.
43 51
44 52 Aliases
45 53 =======
46 54
47 55 All of your $PATH has been loaded as IPython aliases, so you should be
48 56 able to type any normal system command and have it executed. See
49 57 %alias? and %unalias? for details on the alias facilities. See also
50 58 %rehashx? for details on the mechanism used to load $PATH.
51 59
52 60
53 61 Directory management
54 62 ====================
55 63
56 64 Since each command passed by ipython to the underlying system is executed
57 65 in a subshell which exits immediately, you can NOT use !cd to navigate
58 66 the filesystem.
59 67
60 68 IPython provides its own builtin '%cd' magic command to move in the
61 69 filesystem (the % is not required with automagic on). It also maintains
62 70 a list of visited directories (use %dhist to see it) and allows direct
63 71 switching to any of them. Type 'cd?' for more details.
64 72
65 73 %pushd, %popd and %dirs are provided for directory stack handling.
66 74
67 75
68 76 Enabled extensions
69 77 ==================
70 78
71 79 Some extensions, listed below, are enabled as default in this profile.
72 80
73 81 envpersist
74 82 ----------
75 83
76 84 %env can be used to "remember" environment variable manipulations. Examples::
77 85
78 86 %env - Show all environment variables
79 87 %env VISUAL=jed - set VISUAL to jed
80 88 %env PATH+=;/foo - append ;foo to PATH
81 89 %env PATH+=;/bar - also append ;bar to PATH
82 90 %env PATH-=/wbin; - prepend /wbin; to PATH
83 91 %env -d VISUAL - forget VISUAL persistent val
84 92 %env -p - print all persistent env modifications
85 93
86 94 ipy_which
87 95 ---------
88 96
89 97 %which magic command. Like 'which' in unix, but knows about ipython aliases.
90 98
91 99 Example::
92 100
93 101 [C:/ipython]|14> %which st
94 102 st -> start .
95 103 [C:/ipython]|15> %which d
96 104 d -> dir /w /og /on
97 105 [C:/ipython]|16> %which cp
98 106 cp -> cp
99 107 == c:\bin\cp.exe
100 108 c:\bin\cp.exe
101 109
102 110 ipy_app_completers
103 111 ------------------
104 112
105 113 Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu.
106 114
107 115 ipy_rehashdir
108 116 -------------
109 117
110 118 Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir::
111 119
112 120 [~]|22> cd c:/opt/PuTTY/
113 121 [c:opt/PuTTY]|23> rehashdir .
114 122 <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000']
115 123
116 124 Now, you can execute any of those commams directly::
117 125
118 126 [c:opt/PuTTY]|24> cd
119 127 [~]|25> putty
120 128
121 129 (the putty window opens).
122 130
123 131 If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop::
124 132
125 133 [~]|27> for a in _23:
126 134 |..> %store $a
127 135 |..>
128 136 |..>
129 137 Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe')
130 138 Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe')
131 139 Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe')
132 140 Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe')
133 141 ...
134 142
135 143 mglob
136 144 -----
137 145
138 146 Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples::
139 147
140 148 [c:/ipython]|9> mglob *.py
141 149 [c:/ipython]|10> mglob *.py rec:*.txt
142 150 [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:.
143 151
144 152 Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'.
145 153
146 154
147 155 Prompt customization
148 156 ====================
149 157
150 158 The sh profile uses the following prompt configurations::
151 159
152 160 o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>'
153 161 o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>'
154 162
155 163 You can change the prompt configuration to your liking by editing
156 164 ipy_user_conf.py.
157 165
158 166 String lists
159 167 ============
160 168
161 169 String lists (IPython.genutils.SList) are handy way to process output
162 170 from system commands. They are produced by ``var = !cmd`` syntax.
163 171
164 172 First, we acquire the output of 'ls -l'::
165 173
166 174 [Q:doc/examples]|2> lines = !ls -l
167 175 ==
168 176 ['total 23',
169 177 '-rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py',
170 178 '-rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py',
171 179 '-rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py',
172 180 '-rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py',
173 181 '-rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py',
174 182 '-rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py',
175 183 '-rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc']
176 184
177 185 Now, let's take a look at the contents of 'lines' (the first number is
178 186 the list element number)::
179 187
180 188 [Q:doc/examples]|3> lines
181 189 <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
182 190
183 191 0: total 23
184 192 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py
185 193 2: -rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py
186 194 3: -rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py
187 195 4: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py
188 196 5: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py
189 197 6: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py
190 198 7: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc
191 199
192 200 Now, let's filter out the 'embed' lines::
193 201
194 202 [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1)
195 203 [Q:doc/examples]|5> l2
196 204 <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
197 205
198 206 0: total 23
199 207 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py
200 208 2: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py
201 209 3: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py
202 210 4: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py
203 211 5: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc
204 212
205 213 Now, we want strings having just file names and permissions::
206 214
207 215 [Q:doc/examples]|6> l2.fields(8,0)
208 216 <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
209 217
210 218 0: total
211 219 1: example-demo.py -rw-rw-rw-
212 220 2: example-gnuplot.py -rwxrwxrwx
213 221 3: extension.py -rwxrwxrwx
214 222 4: seteditor.py -rwxrwxrwx
215 223 5: seteditor.pyc -rwxrwxrwx
216 224
217 225 Note how the line with 'total' does not raise IndexError.
218 226
219 227 If you want to split these (yielding lists), call fields() without
220 228 arguments::
221 229
222 230 [Q:doc/examples]|7> _.fields()
223 231 <7>
224 232 [['total'],
225 233 ['example-demo.py', '-rw-rw-rw-'],
226 234 ['example-gnuplot.py', '-rwxrwxrwx'],
227 235 ['extension.py', '-rwxrwxrwx'],
228 236 ['seteditor.py', '-rwxrwxrwx'],
229 237 ['seteditor.pyc', '-rwxrwxrwx']]
230 238
231 239 If you want to pass these separated with spaces to a command (typical
232 240 for lists if files), use the .s property::
233 241
234 242
235 243 [Q:doc/examples]|13> files = l2.fields(8).s
236 244 [Q:doc/examples]|14> files
237 245 <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc'
238 246 [Q:doc/examples]|15> ls $files
239 247 example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc
240 248
241 249 SLists are inherited from normal python lists, so every list method is
242 250 available::
243 251
244 252 [Q:doc/examples]|21> lines.append('hey')
245 253
246 254
247 255 Real world example: remove all files outside version control
248 256 ============================================================
249 257
250 258 First, capture output of "hg status"::
251 259
252 260 [Q:/ipython]|28> out = !hg status
253 261 ==
254 262 ['M IPython\\extensions\\ipy_kitcfg.py',
255 263 'M IPython\\extensions\\ipy_rehashdir.py',
256 264 ...
257 265 '? build\\lib\\IPython\\Debugger.py',
258 266 '? build\\lib\\IPython\\extensions\\InterpreterExec.py',
259 267 '? build\\lib\\IPython\\extensions\\InterpreterPasteInput.py',
260 268 ...
261 269
262 270 (lines starting with ? are not under version control).
263 271
264 272 ::
265 273
266 274 [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1)
267 275 [Q:/ipython]|36> junk
268 276 <36> SList (.p, .n, .l, .s, .grep(), .fields() availab
269 277 ...
270 278 10: build\bdist.win32\winexe\temp\_ctypes.py
271 279 11: build\bdist.win32\winexe\temp\_hashlib.py
272 280 12: build\bdist.win32\winexe\temp\_socket.py
273 281
274 282 Now we can just remove these files by doing 'rm $junk.s'.
275 283
276 284 The .s, .n, .p properties
277 285 =========================
278 286
279 287 The '.s' property returns one string where lines are separated by
280 288 single space (for convenient passing to system commands). The '.n'
281 289 property return one string where the lines are separated by '\n'
282 290 (i.e. the original output of the function). If the items in string
283 291 list are file names, '.p' can be used to get a list of "path" objects
284 292 for convenient file manipulation.
285 293
@@ -1,317 +1,325 b''
1 1 .. _tutorial:
2 2
3 3 ======================
4 4 Quick IPython tutorial
5 5 ======================
6 6
7 .. warning::
8
9 As of the 0.11 version of IPython, some of the features and APIs
10 described in this section have been deprecated or are broken. Our plan
11 is to continue to support these features, but they need to be updated
12 to take advantage of recent API changes. Furthermore, this section
13 of the documentation need to be updated to reflect all of these changes.
14
7 15 IPython can be used as an improved replacement for the Python prompt,
8 16 and for that you don't really need to read any more of this manual. But
9 17 in this section we'll try to summarize a few tips on how to make the
10 18 most effective use of it for everyday Python development, highlighting
11 19 things you might miss in the rest of the manual (which is getting long).
12 20 We'll give references to parts in the manual which provide more detail
13 21 when appropriate.
14 22
15 23 The following article by Jeremy Jones provides an introductory tutorial
16 24 about IPython: http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
17 25
18 26 Highlights
19 27 ==========
20 28
21 29 Tab completion
22 30 --------------
23 31
24 32 TAB-completion, especially for attributes, is a convenient way to explore the
25 33 structure of any object you're dealing with. Simply type object_name.<TAB> and
26 34 a list of the object's attributes will be printed (see :ref:`the readline
27 35 section <readline>` for more). Tab completion also works on file and directory
28 36 names, which combined with IPython's alias system allows you to do from within
29 37 IPython many of the things you normally would need the system shell for.
30 38
31 39 Explore your objects
32 40 --------------------
33 41
34 42 Typing object_name? will print all sorts of details about any object,
35 43 including docstrings, function definition lines (for call arguments) and
36 44 constructor details for classes. The magic commands %pdoc, %pdef, %psource
37 45 and %pfile will respectively print the docstring, function definition line,
38 46 full source code and the complete file for any object (when they can be
39 47 found). If automagic is on (it is by default), you don't need to type the '%'
40 48 explicitly. See :ref:`this section <dynamic_object_info>` for more.
41 49
42 50 The `%run` magic command
43 51 ------------------------
44 52
45 53 The %run magic command allows you to run any python script and load all of its
46 54 data directly into the interactive namespace. Since the file is re-read from
47 55 disk each time, changes you make to it are reflected immediately (in contrast
48 56 to the behavior of import). I rarely use import for code I am testing, relying
49 57 on %run instead. See :ref:`this section <magic>` for more on this and other
50 58 magic commands, or type the name of any magic command and ? to get details on
51 59 it. See also :ref:`this section <dreload>` for a recursive reload command. %run
52 60 also has special flags for timing the execution of your scripts (-t) and for
53 61 executing them under the control of either Python's pdb debugger (-d) or
54 62 profiler (-p). With all of these, %run can be used as the main tool for
55 63 efficient interactive development of code which you write in your editor of
56 64 choice.
57 65
58 66 Debug a Python script
59 67 ---------------------
60 68
61 69 Use the Python debugger, pdb. The %pdb command allows you to toggle on and off
62 70 the automatic invocation of an IPython-enhanced pdb debugger (with coloring,
63 71 tab completion and more) at any uncaught exception. The advantage of this is
64 72 that pdb starts inside the function where the exception occurred, with all data
65 73 still available. You can print variables, see code, execute statements and even
66 74 walk up and down the call stack to track down the true source of the problem
67 75 (which often is many layers in the stack above where the exception gets
68 76 triggered). Running programs with %run and pdb active can be an efficient to
69 77 develop and debug code, in many cases eliminating the need for print statements
70 78 or external debugging tools. I often simply put a 1/0 in a place where I want
71 79 to take a look so that pdb gets called, quickly view whatever variables I need
72 80 to or test various pieces of code and then remove the 1/0. Note also that '%run
73 81 -d' activates pdb and automatically sets initial breakpoints for you to step
74 82 through your code, watch variables, etc. The :ref:`output caching section
75 83 <output_caching>` has more details.
76 84
77 85 Use the output cache
78 86 --------------------
79 87
80 88 All output results are automatically stored in a global dictionary named Out
81 89 and variables named _1, _2, etc. alias them. For example, the result of input
82 90 line 4 is available either as Out[4] or as _4. Additionally, three variables
83 91 named _, __ and ___ are always kept updated with the for the last three
84 92 results. This allows you to recall any previous result and further use it for
85 93 new calculations. See :ref:`the output caching section <output_caching>` for
86 94 more.
87 95
88 96 Suppress output
89 97 ---------------
90 98
91 99 Put a ';' at the end of a line to suppress the printing of output. This is
92 100 useful when doing calculations which generate long output you are not
93 101 interested in seeing. The _* variables and the Out[] list do get updated with
94 102 the contents of the output, even if it is not printed. You can thus still
95 103 access the generated results this way for further processing.
96 104
97 105 Input cache
98 106 -----------
99 107
100 108 A similar system exists for caching input. All input is stored in a global
101 109 list called In , so you can re-execute lines 22 through 28 plus line 34 by
102 110 typing 'exec In[22:29]+In[34]' (using Python slicing notation). If you need
103 111 to execute the same set of lines often, you can assign them to a macro with
104 112 the %macro function. See :ref:`here <input_caching>` for more.
105 113
106 114 Use your input history
107 115 ----------------------
108 116
109 117 The %hist command can show you all previous input, without line numbers if
110 118 desired (option -n) so you can directly copy and paste code either back in
111 119 IPython or in a text editor. You can also save all your history by turning on
112 120 logging via %logstart; these logs can later be either reloaded as IPython
113 121 sessions or used as code for your programs.
114 122
115 123 Define your own system aliases
116 124 ------------------------------
117 125
118 126 Even though IPython gives you access to your system shell via the ! prefix,
119 127 it is convenient to have aliases to the system commands you use most often.
120 128 This allows you to work seamlessly from inside IPython with the same commands
121 129 you are used to in your system shell. IPython comes with some pre-defined
122 130 aliases and a complete system for changing directories, both via a stack (see
123 131 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
124 132 visited directories and allows you to go to any previously visited one.
125 133
126 134 Call system shell commands
127 135 --------------------------
128 136
129 137 Use Python to manipulate the results of system commands. The '!!' special
130 138 syntax, and the %sc and %sx magic commands allow you to capture system output
131 139 into Python variables.
132 140
133 141 Use Python variables when calling the shell
134 142 -------------------------------------------
135 143
136 144 Expand python variables when calling the shell (either via '!' and '!!' or via
137 145 aliases) by prepending a $ in front of them. You can also expand complete
138 146 python expressions. See :ref:`our shell section <system_shell_access>` for
139 147 more details.
140 148
141 149 Use profiles
142 150 ------------
143 151
144 152 Use profiles to maintain different configurations (modules to load, function
145 153 definitions, option settings) for particular tasks. You can then have
146 154 customized versions of IPython for specific purposes. :ref:`This section
147 155 <profiles>` has more details.
148 156
149 157
150 158 Embed IPython in your programs
151 159 ------------------------------
152 160
153 161 A few lines of code are enough to load a complete IPython inside your own
154 162 programs, giving you the ability to work with your data interactively after
155 163 automatic processing has been completed. See :ref:`here <embedding>` for more.
156 164
157 165 Use the Python profiler
158 166 -----------------------
159 167
160 168 When dealing with performance issues, the %run command with a -p option
161 169 allows you to run complete programs under the control of the Python profiler.
162 170 The %prun command does a similar job for single Python expressions (like
163 171 function calls).
164 172
165 173 Use IPython to present interactive demos
166 174 ----------------------------------------
167 175
168 176 Use the IPython.demo.Demo class to load any Python script as an interactive
169 177 demo. With a minimal amount of simple markup, you can control the execution of
170 178 the script, stopping as needed. See :ref:`here <interactive_demos>` for more.
171 179
172 180 Run doctests
173 181 ------------
174 182
175 183 Run your doctests from within IPython for development and debugging. The
176 184 special %doctest_mode command toggles a mode where the prompt, output and
177 185 exceptions display matches as closely as possible that of the default Python
178 186 interpreter. In addition, this mode allows you to directly paste in code that
179 187 contains leading '>>>' prompts, even if they have extra leading whitespace
180 188 (as is common in doctest files). This combined with the '%history -tn' call
181 189 to see your translated history (with these extra prompts removed and no line
182 190 numbers) allows for an easy doctest workflow, where you can go from doctest
183 191 to interactive execution to pasting into valid Python code as needed.
184 192
185 193 Source code handling tips
186 194 =========================
187 195
188 196 IPython is a line-oriented program, without full control of the
189 197 terminal. Therefore, it doesn't support true multiline editing. However,
190 198 it has a number of useful tools to help you in dealing effectively with
191 199 more complex editing.
192 200
193 201 The %edit command gives a reasonable approximation of multiline editing,
194 202 by invoking your favorite editor on the spot. IPython will execute the
195 203 code you type in there as if it were typed interactively. Type %edit?
196 204 for the full details on the edit command.
197 205
198 206 If you have typed various commands during a session, which you'd like to
199 207 reuse, IPython provides you with a number of tools. Start by using %hist
200 208 to see your input history, so you can see the line numbers of all input.
201 209 Let us say that you'd like to reuse lines 10 through 20, plus lines 24
202 210 and 28. All the commands below can operate on these with the syntax::
203 211
204 212 %command 10-20 24 28
205 213
206 214 where the command given can be:
207 215
208 216 * %macro <macroname>: this stores the lines into a variable which,
209 217 when called at the prompt, re-executes the input. Macros can be
210 218 edited later using '%edit macroname', and they can be stored
211 219 persistently across sessions with '%store macroname' (the storage
212 220 system is per-profile). The combination of quick macros,
213 221 persistent storage and editing, allows you to easily refine
214 222 quick-and-dirty interactive input into permanent utilities, always
215 223 available both in IPython and as files for general reuse.
216 224 * %edit: this will open a text editor with those lines pre-loaded
217 225 for further modification. It will then execute the resulting
218 226 file's contents as if you had typed it at the prompt.
219 227 * %save <filename>: this saves the lines directly to a named file on
220 228 disk.
221 229
222 230 While %macro saves input lines into memory for interactive re-execution,
223 231 sometimes you'd like to save your input directly to a file. The %save
224 232 magic does this: its input sytnax is the same as %macro, but it saves
225 233 your input directly to a Python file. Note that the %logstart command
226 234 also saves input, but it logs all input to disk (though you can
227 235 temporarily suspend it and reactivate it with %logoff/%logon); %save
228 236 allows you to select which lines of input you need to save.
229 237
230 238
231 239 Lightweight 'version control'
232 240 =============================
233 241
234 242 When you call %edit with no arguments, IPython opens an empty editor
235 243 with a temporary file, and it returns the contents of your editing
236 244 session as a string variable. Thanks to IPython's output caching
237 245 mechanism, this is automatically stored::
238 246
239 247 In [1]: %edit
240 248
241 249 IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
242 250
243 251 Editing... done. Executing edited code...
244 252
245 253 hello - this is a temporary file
246 254
247 255 Out[1]: "print 'hello - this is a temporary file'\n"
248 256
249 257 Now, if you call '%edit -p', IPython tries to open an editor with the
250 258 same data as the last time you used %edit. So if you haven't used %edit
251 259 in the meantime, this same contents will reopen; however, it will be
252 260 done in a new file. This means that if you make changes and you later
253 261 want to find an old version, you can always retrieve it by using its
254 262 output number, via '%edit _NN', where NN is the number of the output
255 263 prompt.
256 264
257 265 Continuing with the example above, this should illustrate this idea::
258 266
259 267 In [2]: edit -p
260 268
261 269 IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
262 270
263 271 Editing... done. Executing edited code...
264 272
265 273 hello - now I made some changes
266 274
267 275 Out[2]: "print 'hello - now I made some changes'\n"
268 276
269 277 In [3]: edit _1
270 278
271 279 IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
272 280
273 281 Editing... done. Executing edited code...
274 282
275 283 hello - this is a temporary file
276 284
277 285 IPython version control at work :)
278 286
279 287 Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
280 288
281 289
282 290 This section was written after a contribution by Alexander Belchenko on
283 291 the IPython user list.
284 292
285 293
286 294 Effective logging
287 295 =================
288 296
289 297 A very useful suggestion sent in by Robert Kern follows:
290 298
291 299 I recently happened on a nifty way to keep tidy per-project log files. I
292 300 made a profile for my project (which is called "parkfield")::
293 301
294 302 include ipythonrc
295 303
296 304 # cancel earlier logfile invocation:
297 305
298 306 logfile ''
299 307
300 308 execute import time
301 309
302 310 execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
303 311
304 312 execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
305 313
306 314 I also added a shell alias for convenience::
307 315
308 316 alias parkfield="ipython -pylab -profile parkfield"
309 317
310 318 Now I have a nice little directory with everything I ever type in,
311 319 organized by project and date.
312 320
313 321 Contribute your own: If you have your own favorite tip on using IPython
314 322 efficiently for a certain task (especially things which can't be done in
315 323 the normal Python interpreter), don't hesitate to send it!
316 324
317 325
@@ -1,234 +1,234 b''
1 1 .. _overview:
2 2
3 3 ============
4 4 Introduction
5 5 ============
6 6
7 7 Overview
8 8 ========
9 9
10 10 One of Python's most useful features is its interactive interpreter.
11 11 This system allows very fast testing of ideas without the overhead of
12 12 creating test files as is typical in most programming languages.
13 13 However, the interpreter supplied with the standard Python distribution
14 14 is somewhat limited for extended interactive use.
15 15
16 16 The goal of IPython is to create a comprehensive environment for
17 17 interactive and exploratory computing. To support this goal, IPython
18 18 has two main components:
19 19
20 20 * An enhanced interactive Python shell.
21 21 * An architecture for interactive parallel computing.
22 22
23 23 All of IPython is open source (released under the revised BSD license).
24 24
25 25 Enhanced interactive Python shell
26 26 =================================
27 27
28 28 IPython's interactive shell (:command:`ipython`), has the following goals,
29 29 amongst others:
30 30
31 31 1. Provide an interactive shell superior to Python's default. IPython
32 32 has many features for object introspection, system shell access,
33 33 and its own special command system for adding functionality when
34 34 working interactively. It tries to be a very efficient environment
35 35 both for Python code development and for exploration of problems
36 36 using Python objects (in situations like data analysis).
37 37
38 38 2. Serve as an embeddable, ready to use interpreter for your own
39 39 programs. IPython can be started with a single call from inside
40 40 another program, providing access to the current namespace. This
41 41 can be very useful both for debugging purposes and for situations
42 42 where a blend of batch-processing and interactive exploration are
43 43 needed. New in the 0.9 version of IPython is a reusable wxPython
44 44 based IPython widget.
45 45
46 46 3. Offer a flexible framework which can be used as the base
47 47 environment for other systems with Python as the underlying
48 48 language. Specifically scientific environments like Mathematica,
49 49 IDL and Matlab inspired its design, but similar ideas can be
50 50 useful in many fields.
51 51
52 52 4. Allow interactive testing of threaded graphical toolkits. IPython
53 53 has support for interactive, non-blocking control of GTK, Qt and
54 54 WX applications via special threading flags. The normal Python
55 55 shell can only do this for Tkinter applications.
56 56
57 57 Main features of the interactive shell
58 58 --------------------------------------
59 59
60 60 * Dynamic object introspection. One can access docstrings, function
61 61 definition prototypes, source code, source files and other details
62 62 of any object accessible to the interpreter with a single
63 63 keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
64 64
65 65 * Searching through modules and namespaces with :samp:`*` wildcards, both
66 66 when using the :samp:`?` system and via the :samp:`%psearch` command.
67 67
68 68 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
69 69 This works for keywords, modules, methods, variables and files in the
70 70 current directory. This is supported via the readline library, and
71 71 full access to configuring readline's behavior is provided.
72 72 Custom completers can be implemented easily for different purposes
73 73 (system commands, magic arguments etc.)
74 74
75 75 * Numbered input/output prompts with command history (persistent
76 76 across sessions and tied to each profile), full searching in this
77 77 history and caching of all input and output.
78 78
79 79 * User-extensible 'magic' commands. A set of commands prefixed with
80 80 :samp:`%` is available for controlling IPython itself and provides
81 81 directory control, namespace information and many aliases to
82 82 common system shell commands.
83 83
84 84 * Alias facility for defining your own system aliases.
85 85
86 86 * Complete system shell access. Lines starting with :samp:`!` are passed
87 87 directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd`
88 88 captures shell output into python variables for further use.
89 89
90 90 * Background execution of Python commands in a separate thread.
91 91 IPython has an internal job manager called jobs, and a
92 92 convenience backgrounding magic function called :samp:`%bg`.
93 93
94 94 * The ability to expand python variables when calling the system shell. In a
95 95 shell command, any python variable prefixed with :samp:`$` is expanded. A
96 96 double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access
97 97 to shell and environment variables like :envvar:`PATH`).
98 98
99 99 * Filesystem navigation, via a magic :samp:`%cd` command, along with a
100 100 persistent bookmark system (using :samp:`%bookmark`) for fast access to
101 101 frequently visited directories.
102 102
103 103 * A lightweight persistence framework via the :samp:`%store` command, which
104 104 allows you to save arbitrary Python variables. These get restored
105 105 automatically when your session restarts.
106 106
107 107 * Automatic indentation (optional) of code as you type (through the
108 108 readline library).
109 109
110 110 * Macro system for quickly re-executing multiple lines of previous
111 111 input with a single name. Macros can be stored persistently via
112 112 :samp:`%store` and edited via :samp:`%edit`.
113 113
114 114 * Session logging (you can then later use these logs as code in your
115 115 programs). Logs can optionally timestamp all input, and also store
116 116 session output (marked as comments, so the log remains valid
117 117 Python source code).
118 118
119 119 * Session restoring: logs can be replayed to restore a previous
120 120 session to the state where you left it.
121 121
122 122 * Verbose and colored exception traceback printouts. Easier to parse
123 123 visually, and in verbose mode they produce a lot of useful
124 124 debugging information (basically a terminal version of the cgitb
125 125 module).
126 126
127 127 * Auto-parentheses: callable objects can be executed without
128 128 parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
129 129
130 130 * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
131 131 auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
132 132 automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
133 133 becomes :samp:`my_function("a b")`.
134 134
135 135 * Extensible input syntax. You can define filters that pre-process
136 136 user input to simplify input in special situations. This allows
137 137 for example pasting multi-line code fragments which start with
138 138 :samp:`>>>` or :samp:`...` such as those from other python sessions or the
139 139 standard Python documentation.
140 140
141 141 * Flexible configuration system. It uses a configuration file which
142 142 allows permanent setting of all command-line options, module
143 143 loading, code and file execution. The system allows recursive file
144 144 inclusion, so you can have a base file with defaults and layers
145 145 which load other customizations for particular projects.
146 146
147 147 * Embeddable. You can call IPython as a python shell inside your own
148 148 python programs. This can be used both for debugging code or for
149 149 providing interactive abilities to your programs with knowledge
150 150 about the local namespaces (very useful in debugging and data
151 151 analysis situations).
152 152
153 153 * Easy debugger access. You can set IPython to call up an enhanced version of
154 154 the Python debugger (pdb) every time there is an uncaught exception. This
155 155 drops you inside the code which triggered the exception with all the data
156 156 live and it is possible to navigate the stack to rapidly isolate the source
157 157 of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run
158 158 any script under pdb's control, automatically setting initial breakpoints for
159 159 you. This version of pdb has IPython-specific improvements, including
160 160 tab-completion and traceback coloring support. For even easier debugger
161 161 access, try :samp:`%debug` after seeing an exception. winpdb is also
162 162 supported, see ipy_winpdb extension.
163 163
164 164 * Profiler support. You can run single statements (similar to
165 165 :samp:`profile.run()`) or complete programs under the profiler's control.
166 166 While this is possible with standard cProfile or profile modules,
167 167 IPython wraps this functionality with magic commands (see :samp:`%prun`
168 168 and :samp:`%run -p`) convenient for rapid interactive work.
169 169
170 170 * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
171 171 that allows you to paste existing doctests (with leading :samp:`>>>`
172 172 prompts and whitespace) and uses doctest-compatible prompts and
173 173 output, so you can use IPython sessions as doctest code.
174 174
175 175 Interactive parallel computing
176 176 ==============================
177 177
178 178 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
179 179 supercomputers, is becoming ubiquitous. Over the last 3 years, we have
180 180 developed an architecture within IPython that allows such hardware to be used
181 181 quickly and easily from Python. Moreover, this architecture is designed to
182 182 support interactive and collaborative parallel computing.
183 183
184 184 The main features of this system are:
185 185
186 186 * Quickly parallelize Python code from an interactive Python/IPython session.
187 187
188 188 * A flexible and dynamic process model that be deployed on anything from
189 189 multicore workstations to supercomputers.
190 190
191 191 * An architecture that supports many different styles of parallelism, from
192 192 message passing to task farming. And all of these styles can be handled
193 193 interactively.
194 194
195 195 * Both blocking and fully asynchronous interfaces.
196 196
197 197 * High level APIs that enable many things to be parallelized in a few lines
198 198 of code.
199 199
200 200 * Write parallel code that will run unchanged on everything from multicore
201 201 workstations to supercomputers.
202 202
203 203 * Full integration with Message Passing libraries (MPI).
204 204
205 205 * Capabilities based security model with full encryption of network connections.
206 206
207 207 * Share live parallel jobs with other users securely. We call this
208 208 collaborative parallel computing.
209 209
210 210 * Dynamically load balanced task farming system.
211 211
212 212 * Robust error handling. Python exceptions raised in parallel execution are
213 213 gathered and presented to the top-level code.
214 214
215 215 For more information, see our :ref:`overview <parallel_index>` of using IPython
216 216 for parallel computing.
217 217
218 218 Portability and Python requirements
219 219 -----------------------------------
220 220
221 221 As of the 0.11 release, IPython works with either Python 2.5 or 2.6.
222 Versions 0.9 and 0.10 worked with Python 2.4 as well. We have not begun
223 the test and port IPython to 3.0. Our plan is to gradually drop Python 2.5
224 support and then begin the transition to strict 2.6 and 3.0.
222 Versions 0.9 and 0.10 worked with Python 2.4 as well. We have not yet begun
223 to test and port IPython to Python 3. Our plan is to gradually drop Python 2.5
224 support and then begin the transition to strict 2.6 and 3.
225 225
226 226 IPython is known to work on the following operating systems:
227 227
228 228 * Linux
229 229 * Most other Unix-like OSs (AIX, Solaris, BSD, etc.)
230 230 * Mac OS X
231 231 * Windows (CygWin, XP, Vista, etc.)
232 232
233 233 See :ref:`here <install_index>` for instructions on how to install IPython.
234 234
@@ -1,23 +1,28 b''
1 1 .. Developers should add in this file, during each release cycle, information
2 2 .. about important changes they've made, in a summary format that's meant for
3 3 .. end users. For each release we normally have three sections: features, bug
4 4 .. fixes and api breakage.
5 5 .. Please remember to credit the authors of the contributions by name,
6 6 .. especially when they are new users or developers who do not regularly
7 7 .. participate in IPython's development.
8 8
9 9 .. _whatsnew_index:
10 10
11 11 =====================
12 12 What's new in IPython
13 13 =====================
14 14
15 This section documents the changes that have been made in various versions of
16 IPython. Users should consult these pages to learn about new features, bug
17 fixes and backwards incompatibilities. Developers should summarize the
18 development work they do here in a user friendly format.
19
15 20 .. toctree::
16 21 :maxdepth: 1
17 22
18 23 development
19 24 version0.10
20 25 version0.9
21 26 version0.8
22 27
23 28
1 NO CONTENT: file was removed
1 NO CONTENT: file was removed
1 NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now