Show More
@@ -8,18 +8,16 b' IPython development guidelines' | |||||
8 | Overview |
|
8 | Overview | |
9 | ======== |
|
9 | ======== | |
10 |
|
10 | |||
11 | IPython is the next generation of IPython. It is named such for two reasons: |
|
11 | Currently, IPython's development tree contains all of the code that used to be | |
12 |
|
12 | part of IPython since the project's inception in 2001, plus all of the effort | ||
13 | - Eventually, IPython will become IPython version 1.0. |
|
13 | that was known for a while (roughly 2004-2008) as `IPython1'. The IPyhton1 | |
14 | - This new code base needs to be able to co-exist with the existing IPython until |
|
14 | development was meant to be an effort to: | |
15 | it is a full replacement for it. Thus we needed a different name. We couldn't |
|
|||
16 | use ``ipython`` (lowercase) as some files systems are case insensitive. |
|
|||
17 |
|
||||
18 | There are two, no three, main goals of the IPython effort: |
|
|||
19 |
|
15 | |||
20 | 1. Clean up the existing codebase and write lots of tests. |
|
16 | 1. Clean up the existing codebase and write lots of tests. | |
21 | 2. Separate the core functionality of IPython from the terminal to enable IPython |
|
17 | ||
22 | to be used from within a variety of GUI applications. |
|
18 | 2. Separate the core functionality of IPython from the terminal to enable | |
|
19 | IPython to be used from within a variety of GUI applications. | |||
|
20 | ||||
23 | 3. Implement a system for interactive parallel computing. |
|
21 | 3. Implement a system for interactive parallel computing. | |
24 |
|
22 | |||
25 | While the third goal may seem a bit unrelated to the main focus of IPython, it |
|
23 | While the third goal may seem a bit unrelated to the main focus of IPython, it | |
@@ -56,6 +54,7 b' subpackages will have its own:' | |||||
56 | - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory |
|
54 | - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory | |
57 | that contains all of the command line scripts associated with the subpackage. |
|
55 | that contains all of the command line scripts associated with the subpackage. | |
58 |
|
56 | |||
|
57 | ||||
59 | Installation and dependencies |
|
58 | Installation and dependencies | |
60 | ----------------------------- |
|
59 | ----------------------------- | |
61 |
|
60 | |||
@@ -127,116 +126,140 b' Specific subpackages' | |||||
127 | Version control |
|
126 | Version control | |
128 | =============== |
|
127 | =============== | |
129 |
|
128 | |||
130 | In the past, IPython development has been done using `Subversion`__. Recently, |
|
129 | All IPython development today is done using the `Bazaar`__ system for | |
131 | we made the transition to using `Bazaar`__ and `Launchpad`__. This makes it |
|
130 | distributed version control and the `Launchpad`__ site for code hosting and bug | |
132 | much easier for people to contribute code to IPython. Here is a sketch of how |
|
131 | tracking. This makes it very easy for anyone to contribute code to IPython. | |
133 | to use Bazaar for IPython development. First, you should install Bazaar. |
|
|||
134 | After you have done that, make sure that it is working by getting the latest |
|
|||
135 | main branch of IPython:: |
|
|||
136 |
|
132 | |||
137 | $ bzr branch lp:ipython |
|
133 | .. __: http://bazaar-vcs.org | |
|
134 | .. __: http://launchpad.net/ipython | |||
138 |
|
135 | |||
139 | Now you can create a new branch for you to do your work in:: |
|
136 | If you are interested in contributing to IPython, you should familiarize a bit | |
|
137 | with how to use bazaar, but this document gives you a concise set of steps to | |||
|
138 | get started. If you are going to become heavily involved with creating code | |||
|
139 | for IPython you'll eventually want to have a Launchpad account (free) so you | |||
|
140 | can publish your own code on the site for review and merging, but small | |||
|
141 | contributions can be simply sent via email to the IPython list as patches. | |||
140 |
|
142 | |||
141 | $ bzr branch ipython ipython-mybranch |
|
143 | Start by creating what Bazaar calls a `shared repository`_: | |
142 |
|
144 | |||
143 | The typical work cycle in this branch will be to make changes in |
|
145 | .. sourcecode:: bash | |
144 | ``ipython-mybranch`` and then commit those changes using the commit command:: |
|
|||
145 |
|
146 | |||
146 | $ ...do work in ipython-mybranch... |
|
147 | # You can choose any name you want instead of "ipython-repo" | |
147 | $ bzr ci -m "the commit message goes here" |
|
148 | bzr init-repo ipython-repo | |
148 |
|
149 | |||
149 | Please note that since we now don't use an old-style linear ChangeLog (that |
|
150 | .. _shared repository: http://bazaar-vcs.org/SharedRepositoryTutorial | |
150 | tends to cause problems with distributed version control systems), you should |
|
|||
151 | ensure that your log messages are reasonably detailed. Use a docstring-like |
|
|||
152 | approach in the commit messages (including the second line being left |
|
|||
153 | *blank*):: |
|
|||
154 |
|
151 | |||
155 | Single line summary of changes being committed. |
|
152 | This creates an empty repository where a lot of related branches can be kept, | |
|
153 | and they all reuse common storage. This way, many operations are very fast and | |||
|
154 | take up less space. Now, go to the newly created repository and make a local | |||
|
155 | branch of the public trunk: | |||
156 |
|
156 | |||
157 | - more details when warranted ... |
|
157 | .. sourcecode:: bash | |
158 | - including crediting outside contributors if they sent the |
|
|||
159 | code/bug/idea! |
|
|||
160 |
|
158 | |||
161 | If we couple this with a policy of making single commits for each reasonably |
|
159 | cd ipython-repo | |
162 | atomic change, the bzr log should give an excellent view of the project, and |
|
160 | # This makes a local copy of the public trunk called "trunk-lp" | |
163 | the `--short` log option becomes a nice summary. |
|
161 | bzr branch lp:ipython trunk-lp | |
|
162 | ||||
|
163 | The ``trunk-lp`` branch is meant to always be a pristine copy of the public | |||
|
164 | trunk. From here, make a personal development copy of the public trunk, where | |||
|
165 | you'll make your changes: | |||
|
166 | ||||
|
167 | .. sourcecode:: bash | |||
164 |
|
168 | |||
165 | While working with this branch, it is a good idea to merge in changes that have |
|
169 | bzr branch trunk-lp trunk-dev | |
166 | been made upstream in the parent branch. This can be done by doing:: |
|
|||
167 |
|
170 | |||
168 | $ bzr pull |
|
171 | Now, your working area looks like this:: | |
169 |
|
172 | |||
170 | If this command shows that the branches have diverged, then you should do a |
|
173 | maqroll[ipython-repo]> ls -a | |
171 | merge instead:: |
|
174 | ./ ../ .bzr/ trunk-dev/ trunk-lp/ | |
|
175 | ||||
|
176 | The ``.bzr`` directory is the Bazaar storage area, and you now have both the | |||
|
177 | reference copy of the public trunk and one working copy for your own | |||
|
178 | development. You can later make further branches as needed (a common workflow | |||
|
179 | is to make branches to contain specific feature implementations until they are | |||
|
180 | ready to be merged). | |||
|
181 | ||||
|
182 | The typical work cycle will be to make changes in ``trunk-dev`` and then commit | |||
|
183 | those changes as often as needed: | |||
172 |
|
184 | |||
173 | $ bzr merge lp:ipython |
|
185 | .. sourcecode:: bash | |
174 |
|
186 | |||
175 | If you want others to be able to see your branch, you can create an account |
|
187 | cd trunk-dev | |
176 | with launchpad and push the branch to your own workspace:: |
|
188 | # ... implement cool new feature... | |
|
189 | bzr commit -m "Commit message goes here." | |||
177 |
|
190 | |||
178 | $ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch |
|
191 | Please note that since we now don't use an old-style linear ChangeLog (that | |
|
192 | tends to cause problems with distributed version control systems), you should | |||
|
193 | ensure that your log messages are reasonably detailed. For non-trivial | |||
|
194 | changes, use a docstring-like approach in the commit messages (including the | |||
|
195 | second line being left *blank*). Type ``bzr commit`` *without* the ``-m`` | |||
|
196 | switch, and Bazaar will open an editor where you can type a more detailed | |||
|
197 | message:: | |||
179 |
|
198 | |||
180 | Finally, once the work in your branch is done, you can merge your changes back |
|
199 | Single line summary of changes being committed. | |
181 | into the `ipython` branch by using merge:: |
|
|||
182 |
|
200 | |||
183 | $ cd ipython |
|
201 | - more details when warranted ... | |
184 | $ merge ../ipython-mybranch |
|
202 | - including crediting outside contributors if they sent the | |
185 | [resolve any conflicts] |
|
203 | code/bug/idea! | |
186 | $ bzr ci -m "Fixing that bug" |
|
|||
187 | $ bzr push |
|
|||
188 |
|
204 | |||
189 | But this will require you to have write permissions to the `ipython` branch. |
|
205 | If we couple this with a policy of making single commits for each reasonably | |
190 | It you don't you can tell one of the IPython devs about your branch and they |
|
206 | atomic change, the bzr log should give an excellent view of the project, and | |
191 | can do the merge for you. |
|
207 | the ``--short`` log option becomes a nice summary. | |
192 |
|
208 | |||
193 | More information about Bazaar workflows can be found `here`__. |
|
209 | As you work on the branch, it's a good idea to frequently keep your copy of the | |
|
210 | trunk updated with respect to Launchpad. This is done via: | |||
194 |
|
211 | |||
195 | .. __: http://subversion.tigris.org/ |
|
212 | .. sourcecode:: bash | |
196 | .. __: http://bazaar-vcs.org/ |
|
|||
197 | .. __: http://www.launchpad.net/ipython |
|
|||
198 | .. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html |
|
|||
199 |
|
213 | |||
200 | Documentation |
|
214 | cd trunk-lp | |
201 | ============= |
|
215 | bzr pull | |
202 |
|
216 | |||
203 | Standalone documentation |
|
217 | Bazaar can then merge any changes that were done to the public trunk into your | |
204 | ------------------------ |
|
218 | local branch via: | |
205 |
|
219 | |||
206 | All standalone documentation should be written in plain text (``.txt``) files |
|
220 | .. sourcecode:: bash | |
207 | using `reStructuredText`_ for markup and formatting. All such documentation |
|
|||
208 | should be placed in the top level directory ``docs`` of the IPython source |
|
|||
209 | tree. Or, when appropriate, a suitably named subdirectory should be used. The |
|
|||
210 | documentation in this location will serve as the main source for IPython |
|
|||
211 | documentation and all existing documentation should be converted to this |
|
|||
212 | format. |
|
|||
213 |
|
221 | |||
214 | In the future, the text files in the ``docs`` directory will be used to |
|
222 | cd trunk-dev | |
215 | generate all forms of documentation for IPython. This include documentation on |
|
223 | bzr merge ../trunk-lp | |
216 | the IPython website as well as *pdf* documentation. |
|
224 | bzr commit -m"Merged upstream changes" | |
217 |
|
225 | |||
218 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html |
|
226 | This workflow ensures that a local copy stays in sync with the public trunk, | |
|
227 | while allowing for local development to be pushed back for public review. | |||
219 |
|
228 | |||
220 | Docstring format |
|
229 | Once your changes are ready for review, you can push them to Launchpad where | |
221 | ---------------- |
|
230 | the IPython team can review them and give you feedback. The first time, use: | |
222 |
|
231 | |||
223 | Good docstrings are very important. All new code will use `Epydoc`_ for |
|
232 | .. sourcecode:: bash | |
224 | generating API docs, so we will follow the `Epydoc`_ conventions. More |
|
|||
225 | specifically, we will use `reStructuredText`_ for markup and formatting, since |
|
|||
226 | it is understood by a wide variety of tools. This means that if in the future |
|
|||
227 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer |
|
|||
228 | transition pains. |
|
|||
229 |
|
233 | |||
230 | Details about using `reStructuredText`_ for docstrings can be found `here |
|
234 | bzr push --remember bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev | |
231 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. |
|
|||
232 |
|
235 | |||
233 | .. _Epydoc: http://epydoc.sourceforge.net/ |
|
236 | where ``<you>`` is your Launchpad user name. This will make this branch | |
|
237 | publicly visible to all. In subsequent uses you can simply run in the branch: | |||
234 |
|
238 | |||
235 | Additional PEPs of interest regarding documentation of code: |
|
239 | .. sourcecode:: bash | |
236 |
|
240 | |||
237 | - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ |
|
241 | bzr push | |
238 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ |
|
242 | ||
239 | - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ |
|
243 | .. note:: | |
|
244 | ||||
|
245 | Before you can push your code to Launchpad, you need to configure your SSH | |||
|
246 | keys. You can do this by clicking on ``Change details`` for your profile | |||
|
247 | and then clicking on the ``SSH Keys`` tab. This should take you to a URL | |||
|
248 | of the form ``https://launchpad.net/~<you>/+editsshkeys`` with instructions | |||
|
249 | on how to upload your keys. | |||
|
250 | ||||
|
251 | Once the branch is publicly visible, using the launchpad interface it can be | |||
|
252 | marked for merging with the link ``Propose for merging into another branch``, | |||
|
253 | leaving the default choice of trunk as its target. This way, Launchpad tracks | |||
|
254 | what changes of this branch are new with respect to the trunk, others in the | |||
|
255 | team can review it, and merge the changes into the trunk. | |||
|
256 | ||||
|
257 | The IPython team has a policy of reviewing all code (both from core members of | |||
|
258 | the team and from external contributors) before merging it. Code should be | |||
|
259 | clearly documented (as explained further in this guide), clear and well tested. | |||
|
260 | We will be happy to provide you with feedback for your code to be a great | |||
|
261 | contribution to the project, and we've found that peer review of code is an | |||
|
262 | excellent way to improve the quality of everyone's work. | |||
240 |
|
263 | |||
241 |
|
264 | |||
242 | Coding conventions |
|
265 | Coding conventions | |
@@ -318,6 +341,86 b' the code, but in general we should remove as many unnecessary ``IP``/``ip``' | |||||
318 | prefixes as possible. However, if a prefix seems absolutely necessary the more |
|
341 | prefixes as possible. However, if a prefix seems absolutely necessary the more | |
319 | specific ``IPY`` or ``ipy`` are preferred. |
|
342 | specific ``IPY`` or ``ipy`` are preferred. | |
320 |
|
343 | |||
|
344 | ||||
|
345 | Documentation | |||
|
346 | ============= | |||
|
347 | ||||
|
348 | Standalone documentation | |||
|
349 | ------------------------ | |||
|
350 | ||||
|
351 | All standalone documentation should be written in plain text (``.txt``) files | |||
|
352 | using `reStructuredText`_ for markup and formatting. All such documentation | |||
|
353 | should be placed in the top level directory ``docs`` of the IPython source | |||
|
354 | tree. Or, when appropriate, a suitably named subdirectory should be used. The | |||
|
355 | documentation in this location will serve as the main source for IPython | |||
|
356 | documentation and all existing documentation should be converted to this | |||
|
357 | format. | |||
|
358 | ||||
|
359 | In the future, the text files in the ``docs`` directory will be used to | |||
|
360 | generate all forms of documentation for IPython. This include documentation on | |||
|
361 | the IPython website as well as *pdf* documentation. | |||
|
362 | ||||
|
363 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |||
|
364 | ||||
|
365 | A bit of shell code: | |||
|
366 | ||||
|
367 | .. sourcecode:: bash | |||
|
368 | ||||
|
369 | cd /tmp | |||
|
370 | echo "My home directory is: $HOME" | |||
|
371 | ls | |||
|
372 | ||||
|
373 | A bit of Python code: | |||
|
374 | ||||
|
375 | .. sourcecode:: python | |||
|
376 | ||||
|
377 | for i in range(10): | |||
|
378 | print i, | |||
|
379 | print "A big number:",2**34 | |||
|
380 | ||||
|
381 | An interactive Python session: | |||
|
382 | ||||
|
383 | .. sourcecode:: python | |||
|
384 | ||||
|
385 | >>> from IPython import genutils | |||
|
386 | >>> genutils.get_ipython_dir() | |||
|
387 | '/home/fperez/.ipython' | |||
|
388 | ||||
|
389 | ||||
|
390 | An IPython session: | |||
|
391 | ||||
|
392 | .. sourcecode:: ipython | |||
|
393 | ||||
|
394 | In [8]: import IPython | |||
|
395 | ||||
|
396 | In [9]: print "This IPython is version:",IPython.__version__ | |||
|
397 | This IPython is version: 0.9.1 | |||
|
398 | ||||
|
399 | ||||
|
400 | ||||
|
401 | Docstring format | |||
|
402 | ---------------- | |||
|
403 | ||||
|
404 | Good docstrings are very important. All new code will use `Epydoc`_ for | |||
|
405 | generating API docs, so we will follow the `Epydoc`_ conventions. More | |||
|
406 | specifically, we will use `reStructuredText`_ for markup and formatting, since | |||
|
407 | it is understood by a wide variety of tools. This means that if in the future | |||
|
408 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer | |||
|
409 | transition pains. | |||
|
410 | ||||
|
411 | Details about using `reStructuredText`_ for docstrings can be found `here | |||
|
412 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. | |||
|
413 | ||||
|
414 | .. _Epydoc: http://epydoc.sourceforge.net/ | |||
|
415 | ||||
|
416 | Additional PEPs of interest regarding documentation of code: | |||
|
417 | ||||
|
418 | - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ | |||
|
419 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ | |||
|
420 | - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ | |||
|
421 | ||||
|
422 | ||||
|
423 | ||||
321 | .. _devel_testing: |
|
424 | .. _devel_testing: | |
322 |
|
425 | |||
323 | Testing system |
|
426 | Testing system |
@@ -1,8 +1,8 b'' | |||||
1 | .. _install_index: |
|
1 | .. _install_index: | |
2 |
|
2 | |||
3 |
============ |
|
3 | ============ | |
4 | Installation |
|
4 | Installation | |
5 |
============ |
|
5 | ============ | |
6 |
|
6 | |||
7 | .. toctree:: |
|
7 | .. toctree:: | |
8 | :maxdepth: 2 |
|
8 | :maxdepth: 2 |
@@ -1,45 +1,90 b'' | |||||
1 | Overview |
|
1 | Overview | |
2 | ======== |
|
2 | ======== | |
3 |
|
3 | |||
4 | This document describes the steps required to install IPython. IPython is organized into a number of subpackages, each of which has its own dependencies. All of the subpackages come with IPython, so you don't need to download and install them separately. However, to use a given subpackage, you will need to install all of its dependencies. |
|
4 | This document describes the steps required to install IPython. IPython is | |
|
5 | organized into a number of subpackages, each of which has its own dependencies. | |||
|
6 | All of the subpackages come with IPython, so you don't need to download and | |||
|
7 | install them separately. However, to use a given subpackage, you will need to | |||
|
8 | install all of its dependencies. | |||
5 |
|
9 | |||
6 |
|
10 | |||
7 | Please let us know if you have problems installing IPython or any of its |
|
11 | Please let us know if you have problems installing IPython or any of its | |
8 |
dependencies. IPython requires Python version 2.4 or greater. We have not |
|
12 | dependencies. IPython requires Python version 2.4 or greater. We have not | |
9 |
IPython with the upcoming 2.6 or 3.0 versions |
|
13 | tested IPython with the upcoming 2.6 or 3.0 versions, though preliminary | |
|
14 | reports of 2.6 usage are encouraging. 3.0 porting will take longer, however. | |||
10 |
|
15 | |||
11 | .. warning:: |
|
16 | .. warning:: | |
12 |
|
17 | |||
13 |
|
|
18 | IPython will not work with Python 2.3 or below. | |
14 |
|
19 | |||
15 | Some of the installation approaches use the :mod:`setuptools` package and its :command:`easy_install` command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. It is not required though. More information about :mod:`setuptools` can be found on its website. |
|
20 | Some of the installation approaches use the :mod:`setuptools` package and its | |
|
21 | :command:`easy_install` command line program. In many scenarios, this provides | |||
|
22 | the most simple method of installing IPython and its dependencies. It is not | |||
|
23 | required though. More information about :mod:`setuptools` can be found on its | |||
|
24 | website. | |||
|
25 | ||||
|
26 | More general information about installing Python packages can be found in | |||
|
27 | Python's documentation at http://www.python.org/doc/. | |||
16 |
|
28 | |||
17 | More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/. |
|
|||
18 |
|
29 | |||
19 | Installing IPython itself |
|
30 | Installing IPython itself | |
20 | ========================= |
|
31 | ========================= | |
21 |
|
32 | |||
22 | Given a properly built Python, the basic interactive IPython shell will work with no external dependencies. However, some Python distributions (particularly on Windows and OS X), don't come with a working :mod:`readline` module. The IPython shell will work without :mod:`readline`, but will lack many features that users depend on, such as tab completion and command line editing. See below for details of how to make sure you have a working :mod:`readline`. |
|
33 | Given a properly built Python, the basic interactive IPython shell will work | |
|
34 | with no external dependencies. However, some Python distributions | |||
|
35 | (particularly on Windows and OS X), don't come with a working :mod:`readline` | |||
|
36 | module. The IPython shell will work without :mod:`readline`, but will lack | |||
|
37 | many features that users depend on, such as tab completion and command line | |||
|
38 | editing. See below for details of how to make sure you have a working | |||
|
39 | :mod:`readline`. | |||
23 |
|
40 | |||
24 | Installation using easy_install |
|
41 | Installation using easy_install | |
25 | ------------------------------- |
|
42 | ------------------------------- | |
26 |
|
43 | |||
27 |
If you have :mod:`setuptools` installed, the easiest way of getting IPython is |
|
44 | If you have :mod:`setuptools` installed, the easiest way of getting IPython is | |
|
45 | to use :command:`easy_install`: | |||
|
46 | ||||
|
47 | .. sourcecode:: bash | |||
|
48 | ||||
|
49 | easy_install IPython | |||
|
50 | ||||
|
51 | Unless you've written a custom distutils script as explained here_, that will | |||
|
52 | try to install either in a default system-wide location, which may require | |||
|
53 | administrator access. If that is the case, you can either run the command with | |||
|
54 | root privileges: | |||
|
55 | ||||
|
56 | .. sourcecode:: bash | |||
|
57 | ||||
|
58 | sudo easy_install IPython | |||
|
59 | ||||
|
60 | or you can specify an alternate location, for example: | |||
28 |
|
61 | |||
29 | $ easy_install IPython |
|
62 | .. sourcecode:: bash | |
|
63 | ||||
|
64 | easy_install --prefix=~/usr/local IPython | |||
|
65 | ||||
|
66 | where this assumes that ``~/usr/local`` is a valid prefix for you to install | |||
|
67 | packages to in your user account. | |||
|
68 | ||||
|
69 | .. _here: http://docs.python.org/install/index.html#inst-config-files | |||
30 |
|
70 | |||
31 | That's it. |
|
|||
32 |
|
71 | |||
33 | Installation from source |
|
72 | Installation from source | |
34 | ------------------------ |
|
73 | ------------------------ | |
35 |
|
74 | |||
36 | If you don't want to use :command:`easy_install`, or don't have it installed, just grab the latest stable build of IPython from `here <http://ipython.scipy.org/dist/>`_. Then do the following:: |
|
75 | If you don't want to use :command:`easy_install`, or don't have it installed, | |
|
76 | just grab the latest stable build of IPython from `here | |||
|
77 | <http://ipython.scipy.org/dist/>`_. Then do the following (using the | |||
|
78 | appropriate version number): | |||
37 |
|
79 | |||
38 | $ tar -xzf ipython.tar.gz |
|
80 | .. sourcecode:: bash | |
39 | $ cd ipython |
|
|||
40 | $ python setup.py install |
|
|||
41 |
|
81 | |||
42 | If you are installing to a location (like ``/usr/local``) that requires higher permissions, you may need to run the last command with :command:`sudo`. |
|
82 | tar -xzf ipython.tar.gz | |
|
83 | cd ipython | |||
|
84 | python setup.py install | |||
|
85 | ||||
|
86 | If you are installing to a location (like ``/usr/local``) that requires higher | |||
|
87 | permissions, you may need to run the last command with :command:`sudo`. | |||
43 |
|
88 | |||
44 | Windows |
|
89 | Windows | |
45 | ------- |
|
90 | ------- | |
@@ -55,22 +100,31 b' There are a few caveats for Windows users. The main issue is that a basic ``pyt' | |||||
55 | Installing the development version |
|
100 | Installing the development version | |
56 | ---------------------------------- |
|
101 | ---------------------------------- | |
57 |
|
102 | |||
58 |
It is also possible to install the development version of IPython from our |
|
103 | It is also possible to install the development version of IPython from our | |
59 | repository. To do this you will need to have Bazaar installed on your system. Then just do:: |
|
104 | `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will | |
|
105 | need to have Bazaar installed on your system. Then just do:: | |||
|
106 | ||||
|
107 | .. sourcecode:: bash | |||
60 |
|
108 | |||
61 |
|
|
109 | bzr branch lp:ipython | |
62 |
|
|
110 | cd ipython | |
63 |
|
|
111 | python setup.py install | |
64 |
|
112 | |||
65 | Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above. |
|
113 | Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above. | |
66 |
|
114 | |||
67 |
Some users want to be able to follow the development branch as it changes. If |
|
115 | Some users want to be able to follow the development branch as it changes. If | |
|
116 | you have :mod:`setuptools` installed, this is easy. Simply replace the last | |||
|
117 | step by: | |||
|
118 | ||||
|
119 | .. sourcecode:: bash | |||
68 |
|
120 | |||
69 |
|
|
121 | python setupegg.py develop | |
70 |
|
122 | |||
71 |
This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do: |
|
123 | This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do: | |
72 |
|
124 | |||
73 | $ bzr pull |
|
125 | .. sourcecode:: bash | |
|
126 | ||||
|
127 | bzr pull | |||
74 |
|
128 | |||
75 | Basic optional dependencies |
|
129 | Basic optional dependencies | |
76 | =========================== |
|
130 | =========================== | |
@@ -92,11 +146,18 b' In principle, all Python distributions should come with a working :mod:`readline' | |||||
92 |
|
146 | |||
93 | * If you are running Windows, which doesn't have a :mod:`readline` module. |
|
147 | * If you are running Windows, which doesn't have a :mod:`readline` module. | |
94 |
|
148 | |||
95 | On OS X, the built-in Python doesn't not have :mod:`readline` because of license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved. For many users, libedit may be sufficient. |
|
149 | On OS X, the built-in Python doesn't not have :mod:`readline` because of | |
|
150 | license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has | |||
|
151 | a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, | |||
|
152 | many of the issues related to the differences between readline and libedit have | |||
|
153 | been resolved. For many users, libedit may be sufficient. | |||
|
154 | ||||
|
155 | Most users on OS X will want to get the full :mod:`readline` module. To get a | |||
|
156 | working :mod:`readline` module, just do (with :mod:`setuptools` installed): | |||
96 |
|
157 | |||
97 | Most users on OS X will want to get the full :mod:`readline` module. To get a working :mod:`readline` module, just do (with :mod:`setuptools` installed):: |
|
158 | .. sourcecode:: bash | |
98 |
|
159 | |||
99 |
|
|
160 | easy_install readline | |
100 |
|
161 | |||
101 | .. note: |
|
162 | .. note: | |
102 |
|
163 | |||
@@ -104,83 +165,126 b' Most users on OS X will want to get the full :mod:`readline` module. To get a w' | |||||
104 | official python.org binaries) already have readline installed so |
|
165 | official python.org binaries) already have readline installed so | |
105 | you don't have to do this step. |
|
166 | you don't have to do this step. | |
106 |
|
167 | |||
107 |
If needed, the readline egg can be build and installed from source (see the |
|
168 | If needed, the readline egg can be build and installed from source (see the | |
|
169 | wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard). | |||
108 |
|
170 | |||
109 | On Windows, you will need the PyReadline module. PyReadline is a separate, Windows only implementation of readline that uses native Windows calls through :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes` module, which comes with Python 2.5 and greater, is required by PyReadline. It is available for Python 2.4 at http://python.net/crew/theller/ctypes. |
|
171 | On Windows, you will need the PyReadline module. PyReadline is a separate, | |
|
172 | Windows only implementation of readline that uses native Windows calls through | |||
|
173 | :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary | |||
|
174 | installer available `here <http://ipython.scipy.org/dist/>`_. The | |||
|
175 | :mod:`ctypes` module, which comes with Python 2.5 and greater, is required by | |||
|
176 | PyReadline. It is available for Python 2.4 at | |||
|
177 | http://python.net/crew/theller/ctypes. | |||
110 |
|
178 | |||
111 | nose |
|
179 | nose | |
112 | ---- |
|
180 | ---- | |
113 |
|
181 | |||
114 | To run the IPython test suite you will need the :mod:`nose` package. Nose provides a great way of sniffing out and running all of the IPython tests. The simplest way of getting nose, is to use :command:`easy_install`:: |
|
182 | To run the IPython test suite you will need the :mod:`nose` package. Nose | |
|
183 | provides a great way of sniffing out and running all of the IPython tests. The | |||
|
184 | simplest way of getting nose, is to use :command:`easy_install`: | |||
|
185 | ||||
|
186 | .. sourcecode:: bash | |||
115 |
|
187 | |||
116 |
|
|
188 | easy_install nose | |
117 |
|
189 | |||
118 |
Another way of getting this is to do: |
|
190 | Another way of getting this is to do: | |
119 |
|
191 | |||
120 | $ easy_install IPython[test] |
|
192 | .. sourcecode:: bash | |
121 |
|
193 | |||
122 | For more installation options, see the `nose website <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose installed, you can run IPython's test suite using the iptest command:: |
|
194 | easy_install IPython[test] | |
123 |
|
195 | |||
124 | $ iptest |
|
196 | For more installation options, see the `nose website | |
|
197 | <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose | |||
|
198 | installed, you can run IPython's test suite using the iptest command: | |||
|
199 | ||||
|
200 | .. sourcecode:: bash | |||
|
201 | ||||
|
202 | iptest | |||
125 |
|
203 | |||
126 |
|
204 | |||
127 | pexpect |
|
205 | pexpect | |
128 | ------- |
|
206 | ------- | |
129 |
|
207 | |||
130 |
The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's |
|
208 | The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's | |
|
209 | :command:`irunner` script. On Unix platforms (including OS X), just do: | |||
|
210 | ||||
|
211 | .. sourcecode:: bash | |||
131 |
|
212 | |||
132 |
|
|
213 | easy_install pexpect | |
133 |
|
214 | |||
134 | Windows users are out of luck as pexpect does not run there. |
|
215 | Windows users are out of luck as pexpect does not run there. | |
135 |
|
216 | |||
136 | Dependencies for IPython.kernel (parallel computing) |
|
217 | Dependencies for IPython.kernel (parallel computing) | |
137 | ==================================================== |
|
218 | ==================================================== | |
138 |
|
219 | |||
139 | The IPython kernel provides a nice architecture for parallel computing. The main focus of this architecture is on interactive parallel computing. These features require a number of additional packages: |
|
220 | The IPython kernel provides a nice architecture for parallel computing. The | |
|
221 | main focus of this architecture is on interactive parallel computing. These | |||
|
222 | features require a number of additional packages: | |||
140 |
|
223 | |||
141 | * zope.interface (yep, we use interfaces) |
|
224 | * zope.interface (yep, we use interfaces) | |
142 | * Twisted (asynchronous networking framework) |
|
225 | * Twisted (asynchronous networking framework) | |
143 | * Foolscap (a nice, secure network protocol) |
|
226 | * Foolscap (a nice, secure network protocol) | |
144 | * pyOpenSSL (security for network connections) |
|
227 | * pyOpenSSL (security for network connections) | |
145 |
|
228 | |||
146 |
On a Unix style platform (including OS X), if you want to use |
|
229 | On a Unix style platform (including OS X), if you want to use | |
|
230 | :mod:`setuptools`, you can just do: | |||
147 |
|
231 | |||
148 | $ easy_install IPython[kernel] # the first three |
|
232 | .. sourcecode:: bash | |
149 | $ easy_install IPython[security] # pyOpenSSL |
|
233 | ||
|
234 | easy_install IPython[kernel] # the first three | |||
|
235 | easy_install IPython[security] # pyOpenSSL | |||
150 |
|
236 | |||
151 | zope.interface and Twisted |
|
237 | zope.interface and Twisted | |
152 | -------------------------- |
|
238 | -------------------------- | |
153 |
|
239 | |||
154 |
On Unix style platforms (including OS X), the simplest way of getting the these |
|
240 | On Unix style platforms (including OS X), the simplest way of getting the these | |
|
241 | is to use :command:`easy_install`: | |||
|
242 | ||||
|
243 | .. sourcecode:: bash | |||
155 |
|
244 | |||
156 |
|
|
245 | easy_install zope.interface | |
157 |
|
|
246 | easy_install Twisted | |
158 |
|
247 | |||
159 | Of course, you can also download the source tarballs from the `Twisted website <twistedmatrix.org>`_ and the `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python setup.py install`` if you prefer. |
|
248 | Of course, you can also download the source tarballs from the `Twisted website | |
|
249 | <twistedmatrix.org>`_ and the `zope.interface page at PyPI | |||
|
250 | <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python | |||
|
251 | setup.py install`` if you prefer. | |||
160 |
|
252 | |||
161 | 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. |
|
253 | Windows is a bit different. For zope.interface and Twisted, simply get the | |
|
254 | latest binary ``.exe`` installer from the Twisted website. This installer | |||
|
255 | includes both zope.interface and Twisted and should just work. | |||
162 |
|
256 | |||
163 | Foolscap |
|
257 | Foolscap | |
164 | -------- |
|
258 | -------- | |
165 |
|
259 | |||
166 |
Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to |
|
260 | Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to | |
|
261 | implement our parallel computing features. | |||
|
262 | ||||
|
263 | On all platforms a simple: | |||
167 |
|
264 | |||
168 | On all platforms a simple:: |
|
265 | .. sourcecode:: bash | |
169 |
|
266 | |||
170 |
|
|
267 | easy_install foolscap | |
171 |
|
268 | |||
172 |
should work. You can also download the source tarballs from the `Foolscap |
|
269 | should work. You can also download the source tarballs from the `Foolscap | |
|
270 | website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install`` | |||
|
271 | if you prefer. | |||
173 |
|
272 | |||
174 | pyOpenSSL |
|
273 | pyOpenSSL | |
175 | --------- |
|
274 | --------- | |
176 |
|
275 | |||
177 |
IPython requires an older version of pyOpenSSL (0.6 rather than the current |
|
276 | IPython requires an older version of pyOpenSSL (0.6 rather than the current | |
|
277 | 0.7). There are a couple of options for getting this: | |||
|
278 | ||||
|
279 | 1. Most Linux distributions have packages for pyOpenSSL. | |||
|
280 | ||||
|
281 | 2. The built-in Python 2.5 on OS X 10.5 already has it installed. | |||
|
282 | ||||
|
283 | 3. There are source tarballs on the pyOpenSSL website. On Unix-like | |||
|
284 | platforms, these can be built using ``python seutp.py install``. | |||
178 |
|
285 | |||
179 | 1. Most Linux distributions have packages for pyOpenSSL. |
|
286 | 4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website | |
180 | 2. The built-in Python 2.5 on OS X 10.5 already has it installed. |
|
287 | <http://pyopenssl.sourceforge.net/>`_. | |
181 | 3. There are source tarballs on the pyOpenSSL website. On Unix-like |
|
|||
182 | platforms, these can be built using ``python seutp.py install``. |
|
|||
183 | 4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_. |
|
|||
184 |
|
288 | |||
185 | Dependencies for IPython.frontend (the IPython GUI) |
|
289 | Dependencies for IPython.frontend (the IPython GUI) | |
186 | =================================================== |
|
290 | =================================================== | |
@@ -188,4 +292,9 b' Dependencies for IPython.frontend (the IPython GUI)' | |||||
188 | wxPython |
|
292 | wxPython | |
189 | -------- |
|
293 | -------- | |
190 |
|
294 | |||
191 | Starting with IPython 0.9, IPython has a new IPython.frontend package that has a nice wxPython based IPython GUI. As you would expect, this GUI requires wxPython. Most Linux distributions have wxPython packages available and the built-in Python on OS X comes with wxPython preinstalled. For Windows, a binary installer is available on the `wxPython website <http://www.wxpython.org/>`_. No newline at end of file |
|
295 | Starting with IPython 0.9, IPython has a new IPython.frontend package that has | |
|
296 | a nice wxPython based IPython GUI. As you would expect, this GUI requires | |||
|
297 | wxPython. Most Linux distributions have wxPython packages available and the | |||
|
298 | built-in Python on OS X comes with wxPython preinstalled. For Windows, a | |||
|
299 | binary installer is available on the `wxPython website | |||
|
300 | <http://www.wxpython.org/>`_. No newline at end of file |
@@ -91,10 +91,10 b' Main features of the interactive shell' | |||||
91 | IPython has an internal job manager called jobs, and a |
|
91 | IPython has an internal job manager called jobs, and a | |
92 | convenience backgrounding magic function called :samp:`%bg`. |
|
92 | convenience backgrounding magic function called :samp:`%bg`. | |
93 |
|
93 | |||
94 | * The ability to expand python variables when calling the system |
|
94 | * The ability to expand python variables when calling the system shell. In a | |
95 |
shell |
|
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 | * Filesystem navigation, via a magic :samp:`%cd` command, along with a |
|
99 | * Filesystem navigation, via a magic :samp:`%cd` command, along with a | |
100 | persistent bookmark system (using :samp:`%bookmark`) for fast access to |
|
100 | persistent bookmark system (using :samp:`%bookmark`) for fast access to | |
@@ -150,17 +150,16 b' Main features of the interactive shell' | |||||
150 | about the local namespaces (very useful in debugging and data |
|
150 | about the local namespaces (very useful in debugging and data | |
151 | analysis situations). |
|
151 | analysis situations). | |
152 |
|
152 | |||
153 | * Easy debugger access. You can set IPython to call up an enhanced |
|
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 | the exception with all the data live and it is possible to |
|
156 | live and it is possible to navigate the stack to rapidly isolate the source | |
157 | navigate the stack to rapidly isolate the source of a bug. The |
|
157 | of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run | |
158 | :samp:`%run` magic command (with the :samp:`-d` option) can run any script under |
|
158 | any script under pdb's control, automatically setting initial breakpoints for | |
159 | pdb's control, automatically setting initial breakpoints for you. |
|
159 | you. This version of pdb has IPython-specific improvements, including | |
160 | This version of pdb has IPython-specific improvements, including |
|
160 | tab-completion and traceback coloring support. For even easier debugger | |
161 | tab-completion and traceback coloring support. For even easier |
|
161 | access, try :samp:`%debug` after seeing an exception. winpdb is also | |
162 | debugger access, try :samp:`%debug` after seeing an exception. winpdb is |
|
162 | supported, see ipy_winpdb extension. | |
163 | also supported, see ipy_winpdb extension. |
|
|||
164 |
|
163 | |||
165 | * Profiler support. You can run single statements (similar to |
|
164 | * Profiler support. You can run single statements (similar to | |
166 | :samp:`profile.run()`) or complete programs under the profiler's control. |
|
165 | :samp:`profile.run()`) or complete programs under the profiler's control. | |
@@ -176,10 +175,11 b' Main features of the interactive shell' | |||||
176 | Interactive parallel computing |
|
175 | Interactive parallel computing | |
177 | ============================== |
|
176 | ============================== | |
178 |
|
177 | |||
179 |
Increasingly, parallel computer hardware, such as multicore CPUs, clusters and |
|
178 | Increasingly, parallel computer hardware, such as multicore CPUs, clusters and | |
180 | architecture within IPython that allows such hardware to be used quickly and easily |
|
179 | supercomputers, is becoming ubiquitous. Over the last 3 years, we have | |
181 | from Python. Moreover, this architecture is designed to support interactive and |
|
180 | developed an architecture within IPython that allows such hardware to be used | |
182 | collaborative parallel computing. |
|
181 | quickly and easily from Python. Moreover, this architecture is designed to | |
|
182 | support interactive and collaborative parallel computing. | |||
183 |
|
183 | |||
184 | The main features of this system are: |
|
184 | The main features of this system are: | |
185 |
|
185 | |||
@@ -204,16 +204,16 b' The main features of this system are:' | |||||
204 |
|
204 | |||
205 | * Capabilities based security model with full encryption of network connections. |
|
205 | * Capabilities based security model with full encryption of network connections. | |
206 |
|
206 | |||
207 |
* Share live parallel jobs with other users securely. We call this |
|
207 | * Share live parallel jobs with other users securely. We call this | |
208 | parallel computing. |
|
208 | collaborative parallel computing. | |
209 |
|
209 | |||
210 | * Dynamically load balanced task farming system. |
|
210 | * Dynamically load balanced task farming system. | |
211 |
|
211 | |||
212 | * Robust error handling. Python exceptions raised in parallel execution are |
|
212 | * Robust error handling. Python exceptions raised in parallel execution are | |
213 | gathered and presented to the top-level code. |
|
213 | gathered and presented to the top-level code. | |
214 |
|
214 | |||
215 |
For more information, see our :ref:`overview <parallel_index>` of using IPython |
|
215 | For more information, see our :ref:`overview <parallel_index>` of using IPython | |
216 | parallel computing. |
|
216 | for parallel computing. | |
217 |
|
217 | |||
218 | Portability and Python requirements |
|
218 | Portability and Python requirements | |
219 | ----------------------------------- |
|
219 | ----------------------------------- | |
@@ -225,8 +225,7 b' work with some minor changes.' | |||||
225 | IPython is known to work on the following operating systems: |
|
225 | IPython is known to work on the following operating systems: | |
226 |
|
226 | |||
227 | * Linux |
|
227 | * Linux | |
228 | * AIX |
|
228 | * Most other Unix-like OSs (AIX, Solaris, BSD, etc.) | |
229 | * Most other Unix-like OSs (Solaris, BSD, etc.) |
|
|||
230 | * Mac OS X |
|
229 | * Mac OS X | |
231 | * Windows (CygWin, XP, Vista, etc.) |
|
230 | * Windows (CygWin, XP, Vista, etc.) | |
232 |
|
231 |
@@ -11,4 +11,4 b' Using IPython for parallel computing' | |||||
11 | parallel_multiengine.txt |
|
11 | parallel_multiengine.txt | |
12 | parallel_task.txt |
|
12 | parallel_task.txt | |
13 | parallel_mpi.txt |
|
13 | parallel_mpi.txt | |
14 |
|
14 | visionhpc.txt |
1 | NO CONTENT: modified file chmod 100644 => 100755 |
|
NO CONTENT: modified file chmod 100644 => 100755 |
General Comments 0
You need to be logged in to leave comments.
Login now