Show More
@@ -8,143 +8,72 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 | This document describes IPython from the perspective of developers. Most | |
12 |
|
12 | importantly, it gives information for people who want to contribute to the | ||
13 | - Eventually, IPython will become IPython version 1.0. |
|
13 | development of IPython. So if you want to help out, read on! | |
14 | - This new code base needs to be able to co-exist with the existing IPython until |
|
14 | ||
15 | it is a full replacement for it. Thus we needed a different name. We couldn't |
|
15 | How to contribute to IPython | |
16 | use ``ipython`` (lowercase) as some files systems are case insensitive. |
|
16 | ============================ | |
17 |
|
17 | |||
18 | There are two, no three, main goals of the IPython effort: |
|
18 | IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_. | |
19 |
|
19 | This makes it easy for people to contribute to the development of IPython. | ||
20 | 1. Clean up the existing codebase and write lots of tests. |
|
20 | Here is a sketch of how to get going. | |
21 | 2. Separate the core functionality of IPython from the terminal to enable IPython |
|
|||
22 | to be used from within a variety of GUI applications. |
|
|||
23 | 3. Implement a system for interactive parallel computing. |
|
|||
24 |
|
||||
25 | While the third goal may seem a bit unrelated to the main focus of IPython, it |
|
|||
26 | turns out that the technologies required for this goal are nearly identical |
|
|||
27 | with those required for goal two. This is the main reason the interactive |
|
|||
28 | parallel computing capabilities are being put into IPython proper. Currently |
|
|||
29 | the third of these goals is furthest along. |
|
|||
30 |
|
||||
31 | This document describes IPython from the perspective of developers. |
|
|||
32 |
|
||||
33 |
|
||||
34 | Project organization |
|
|||
35 | ==================== |
|
|||
36 |
|
||||
37 | Subpackages |
|
|||
38 | ----------- |
|
|||
39 |
|
||||
40 | IPython is organized into semi self-contained subpackages. Each of the |
|
|||
41 | subpackages will have its own: |
|
|||
42 |
|
||||
43 | - **Dependencies**. One of the most important things to keep in mind in |
|
|||
44 | partitioning code amongst subpackages, is that they should be used to cleanly |
|
|||
45 | encapsulate dependencies. |
|
|||
46 |
|
||||
47 | - **Tests**. Each subpackage shoud have its own ``tests`` subdirectory that |
|
|||
48 | contains all of the tests for that package. For information about writing |
|
|||
49 | tests for IPython, see the `Testing System`_ section of this document. |
|
|||
50 |
|
||||
51 | - **Configuration**. Each subpackage should have its own ``config`` |
|
|||
52 | subdirectory that contains the configuration information for the components |
|
|||
53 | of the subpackage. For information about how the IPython configuration |
|
|||
54 | system works, see the `Configuration System`_ section of this document. |
|
|||
55 |
|
||||
56 | - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory |
|
|||
57 | that contains all of the command line scripts associated with the subpackage. |
|
|||
58 |
|
||||
59 | Installation and dependencies |
|
|||
60 | ----------------------------- |
|
|||
61 |
|
||||
62 | IPython will not use `setuptools`_ for installation. Instead, we will use |
|
|||
63 | standard ``setup.py`` scripts that use `distutils`_. While there are a number a |
|
|||
64 | extremely nice features that `setuptools`_ has (like namespace packages), the |
|
|||
65 | current implementation of `setuptools`_ has performance problems, particularly |
|
|||
66 | on shared file systems. In particular, when Python packages are installed on |
|
|||
67 | NSF file systems, import times become much too long (up towards 10 seconds). |
|
|||
68 |
|
||||
69 | Because IPython is being used extensively in the context of high performance |
|
|||
70 | computing, where performance is critical but shared file systems are common, we |
|
|||
71 | feel these performance hits are not acceptable. Thus, until the performance |
|
|||
72 | problems associated with `setuptools`_ are addressed, we will stick with plain |
|
|||
73 | `distutils`_. We are hopeful that these problems will be addressed and that we |
|
|||
74 | will eventually begin using `setuptools`_. Because of this, we are trying to |
|
|||
75 | organize IPython in a way that will make the eventual transition to |
|
|||
76 | `setuptools`_ as painless as possible. |
|
|||
77 |
|
||||
78 | Because we will be using `distutils`_, there will be no method for |
|
|||
79 | automatically installing dependencies. Instead, we are following the approach |
|
|||
80 | of `Matplotlib`_ which can be summarized as follows: |
|
|||
81 |
|
||||
82 | - Distinguish between required and optional dependencies. However, the required |
|
|||
83 | dependencies for IPython should be only the Python standard library. |
|
|||
84 |
|
||||
85 | - Upon installation check to see which optional dependencies are present and |
|
|||
86 | tell the user which parts of IPython need which optional dependencies. |
|
|||
87 |
|
||||
88 | It is absolutely critical that each subpackage of IPython has a clearly |
|
|||
89 | specified set of dependencies and that dependencies are not carelessly |
|
|||
90 | inherited from other IPython subpackages. Furthermore, tests that have certain |
|
|||
91 | dependencies should not fail if those dependencies are not present. Instead |
|
|||
92 | they should be skipped and print a message. |
|
|||
93 |
|
||||
94 | .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools |
|
|||
95 | .. _distutils: http://docs.python.org/lib/module-distutils.html |
|
|||
96 | .. _Matplotlib: http://matplotlib.sourceforge.net/ |
|
|||
97 |
|
||||
98 | Specific subpackages |
|
|||
99 | -------------------- |
|
|||
100 |
|
||||
101 | ``core`` |
|
|||
102 | This is the core functionality of IPython that is independent of the |
|
|||
103 | terminal, network and GUIs. Most of the code that is in the current |
|
|||
104 | IPython trunk will be refactored, cleaned up and moved here. |
|
|||
105 |
|
||||
106 | ``kernel`` |
|
|||
107 | The enables the IPython core to be expose to a the network. This is |
|
|||
108 | also where all of the parallel computing capabilities are to be found. |
|
|||
109 |
|
||||
110 | ``config`` |
|
|||
111 | The configuration package used by IPython. |
|
|||
112 |
|
21 | |||
113 | ``frontends`` |
|
22 | Install Bazaar and create a Launchpad account | |
114 | The various frontends for IPython. A frontend is the end-user application |
|
23 | --------------------------------------------- | |
115 | that exposes the capabilities of IPython to the user. The most basic |
|
|||
116 | frontend will simply be a terminal based application that looks just like |
|
|||
117 | today 's IPython. Other frontends will likely be more powerful and based |
|
|||
118 | on GUI toolkits. |
|
|||
119 |
|
24 | |||
120 | ``notebook`` |
|
25 | First make sure you have installed Bazaar (see their `website | |
121 | An application that allows users to work with IPython notebooks. |
|
26 | <http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about | |
|
27 | you, try the following:: | |||
122 |
|
28 | |||
123 | ``tools`` |
|
29 | $ bzr whoami | |
124 | This is where general utilities go. |
|
30 | Joe Coder <jcoder@gmail.com> | |
125 |
|
31 | |||
|
32 | This should display your name and email. Next, you will want to create an | |||
|
33 | account on the `Launchpad website <http://www.launchpad.net>`_ and setup your | |||
|
34 | ssh keys. For more information of setting up your ssh keys, see `this link | |||
|
35 | <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_. | |||
126 |
|
36 | |||
127 | Version control |
|
37 | Get the main IPython branch from Launchpad | |
128 | =============== |
|
38 | ------------------------------------------ | |
129 |
|
39 | |||
130 | In the past, IPython development has been done using `Subversion`__. Recently, |
|
40 | Now, you can get a copy of the main IPython development branch (we call this | |
131 | we made the transition to using `Bazaar`__ and `Launchpad`__. This makes it |
|
41 | the "trunk"):: | |
132 | much easier for people to contribute code to IPython. Here is a sketch of how |
|
|||
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 |
|
42 | |||
137 | $ bzr branch lp:ipython |
|
43 | $ bzr branch lp:ipython | |
138 |
|
44 | |||
139 | Now you can create a new branch for you to do your work in:: |
|
45 | Create a working branch | |
|
46 | ----------------------- | |||
|
47 | ||||
|
48 | When working on IPython, you won't actually make edits directly to the | |||
|
49 | :file:`lp:ipython` branch. Instead, you will create a separate branch for your | |||
|
50 | changes. For now, let's assume you want to do your work in a branch named | |||
|
51 | "ipython-mybranch". Create this branch by doing:: | |||
140 |
|
52 | |||
141 | $ bzr branch ipython ipython-mybranch |
|
53 | $ bzr branch ipython ipython-mybranch | |
142 |
|
54 | |||
143 | The typical work cycle in this branch will be to make changes in |
|
55 | When you actually create a branch, you will want to give it a name that | |
144 | ``ipython-mybranch`` and then commit those changes using the commit command:: |
|
56 | reflects the nature of the work that you will be doing in it, like | |
|
57 | "install-docs-update". | |||
|
58 | ||||
|
59 | Make edits in your working branch | |||
|
60 | --------------------------------- | |||
|
61 | ||||
|
62 | Now you are ready to actually make edits in your :file:`ipython-mybranch` | |||
|
63 | branch. Before doing this, it is helpful to install this branch so you can | |||
|
64 | test your changes as you work. This is easiest if you have setuptools | |||
|
65 | installed. Then, just do:: | |||
|
66 | ||||
|
67 | $ cd ipython-mybranch | |||
|
68 | $ python setupegg.py develop | |||
|
69 | ||||
|
70 | Now, make some changes. After a while, you will want to commit your changes. | |||
|
71 | This let's Bazaar know that you like the changes you have made and gives you | |||
|
72 | an opportunity to keep a nice record of what you have done. This looks like | |||
|
73 | this:: | |||
145 |
|
74 | |||
146 | $ ...do work in ipython-mybranch... |
|
75 | $ ...do work in ipython-mybranch... | |
147 | $ bzr ci -m "the commit message goes here" |
|
76 | $ bzr commit -m "the commit message goes here" | |
148 |
|
77 | |||
149 | Please note that since we now don't use an old-style linear ChangeLog (that |
|
78 | Please note that since we now don't use an old-style linear ChangeLog (that | |
150 | tends to cause problems with distributed version control systems), you should |
|
79 | tends to cause problems with distributed version control systems), you should | |
@@ -154,48 +83,60 b' approach in the commit messages (including the second line being left' | |||||
154 |
|
83 | |||
155 | Single line summary of changes being committed. |
|
84 | Single line summary of changes being committed. | |
156 |
|
85 | |||
157 |
|
|
86 | * more details when warranted ... | |
158 |
|
|
87 | * including crediting outside contributors if they sent the | |
159 | code/bug/idea! |
|
88 | code/bug/idea! | |
160 |
|
89 | |||
161 | If we couple this with a policy of making single commits for each reasonably |
|
90 | As you work, you will repeat this edit/commit cycle many times. If you work on | |
162 | atomic change, the bzr log should give an excellent view of the project, and |
|
91 | your branch for a long time, you will also want to get the latest changes from | |
163 | the `--short` log option becomes a nice summary. |
|
92 | the :file:`lp:ipython` branch. This can be done with the following sequence of | |
|
93 | commands:: | |||
164 |
|
94 | |||
165 | While working with this branch, it is a good idea to merge in changes that have |
|
95 | $ ls | |
166 | been made upstream in the parent branch. This can be done by doing:: |
|
96 | ipython | |
167 |
|
97 | ipython-mybranch | ||
168 | $ bzr pull |
|
|||
169 |
|
98 | |||
170 | If this command shows that the branches have diverged, then you should do a |
|
99 | $ cd ipython | |
171 | merge instead:: |
|
100 | $ bzr pull | |
|
101 | $ cd ../ipython-mybranch | |||
|
102 | $ bzr merge ../ipython | |||
|
103 | $ bzr commit -m "Merging changes from trunk" | |||
172 |
|
104 | |||
173 | $ bzr merge lp:ipython |
|
105 | Along the way, you should also run the IPython test suite. You can do this using the :command:`iptest` command:: | |
174 |
|
106 | |||
175 | If you want others to be able to see your branch, you can create an account |
|
107 | $ cd | |
176 | with launchpad and push the branch to your own workspace:: |
|
108 | $ iptest | |
177 |
|
109 | |||
178 | $ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch |
|
110 | The :command:`iptest` command will also pick up and run any tests you have written. | |
179 |
|
111 | |||
180 | Finally, once the work in your branch is done, you can merge your changes back |
|
112 | Post your branch and request a code review | |
181 | into the `ipython` branch by using merge:: |
|
113 | ------------------------------------------ | |
182 |
|
114 | |||
183 | $ cd ipython |
|
115 | Once you are done with your edits, you should post your branch on Launchpad so | |
184 | $ merge ../ipython-mybranch |
|
116 | that other IPython developers can review the changes and help you merge your | |
185 | [resolve any conflicts] |
|
117 | changes into the main development branch. To post your branch on Launchpad, | |
186 | $ bzr ci -m "Fixing that bug" |
|
118 | do:: | |
187 | $ bzr push |
|
119 | ||
|
120 | $ cd ipython-mybranch | |||
|
121 | $ bzr push lp:~yourusername/ipython/ipython-mybranch | |||
|
122 | ||||
|
123 | Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you | |||
|
124 | should see your branch under the "Code" tab. If you click on your branch, you | |||
|
125 | can provide a short description of the branch as well as mark its status. Most | |||
|
126 | importantly, you should click the link that reads "Propose for merging into | |||
|
127 | another branch". What does this do? | |||
188 |
|
128 | |||
189 | But this will require you to have write permissions to the `ipython` branch. |
|
129 | This let's the other IPython developers know that your branch is ready to be | |
190 | It you don't you can tell one of the IPython devs about your branch and they |
|
130 | reviewed and merged into the main development branch. During this review | |
191 | can do the merge for you. |
|
131 | process, other developers will give you feedback and help you get your code | |
|
132 | ready to be merged. What types of things will we be looking for: | |||
192 |
|
133 | |||
193 | More information about Bazaar workflows can be found `here`__. |
|
134 | * All code is documented. | |
|
135 | * All code has tests. | |||
|
136 | * The entire IPython test suite passes. | |||
194 |
|
137 | |||
195 | .. __: http://subversion.tigris.org/ |
|
138 | Once your changes have been reviewed and approved, someone will merge them | |
196 | .. __: http://bazaar-vcs.org/ |
|
139 | into the main development branch. | |
197 | .. __: http://www.launchpad.net/ipython |
|
|||
198 | .. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html |
|
|||
199 |
|
140 | |||
200 | Documentation |
|
141 | Documentation | |
201 | ============= |
|
142 | ============= | |
@@ -204,39 +145,31 b' Standalone documentation' | |||||
204 | ------------------------ |
|
145 | ------------------------ | |
205 |
|
146 | |||
206 | All standalone documentation should be written in plain text (``.txt``) files |
|
147 | All standalone documentation should be written in plain text (``.txt``) files | |
207 |
using |
|
148 | using reStructuredText [reStructuredText]_ for markup and formatting. All such | |
208 |
should be placed in |
|
149 | documentation should be placed in directory :file:`docs/source` of the IPython | |
209 | tree. Or, when appropriate, a suitably named subdirectory should be used. The |
|
150 | source tree. The documentation in this location will serve as the main source | |
210 | documentation in this location will serve as the main source for IPython |
|
151 | for IPython documentation and all existing documentation should be converted | |
211 | documentation and all existing documentation should be converted to this |
|
152 | to this format. | |
212 | format. |
|
|||
213 |
|
153 | |||
214 | In the future, the text files in the ``docs`` directory will be used to |
|
154 | To build the final documentation, we use Sphinx [Sphinx]_. Once you have Sphinx installed, you can build the html docs yourself by doing:: | |
215 | generate all forms of documentation for IPython. This include documentation on |
|
|||
216 | the IPython website as well as *pdf* documentation. |
|
|||
217 |
|
155 | |||
218 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html |
|
156 | $ cd ipython-mybranch/docs | |
|
157 | $ make html | |||
219 |
|
158 | |||
220 | Docstring format |
|
159 | Docstring format | |
221 | ---------------- |
|
160 | ---------------- | |
222 |
|
161 | |||
223 |
Good docstrings are very important. All new code |
|
162 | Good docstrings are very important. All new code should have docstrings that | |
224 | generating API docs, so we will follow the `Epydoc`_ conventions. More |
|
163 | are formatted using reStructuredText for markup and formatting, since it is | |
225 | specifically, we will use `reStructuredText`_ for markup and formatting, since |
|
164 | understood by a wide variety of tools. Details about using reStructuredText | |
226 | it is understood by a wide variety of tools. This means that if in the future |
|
165 | for docstrings can be found `here | |
227 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer |
|
|||
228 | transition pains. |
|
|||
229 |
|
||||
230 | Details about using `reStructuredText`_ for docstrings can be found `here |
|
|||
231 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. |
|
166 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. | |
232 |
|
167 | |||
233 | .. _Epydoc: http://epydoc.sourceforge.net/ |
|
|||
234 |
|
||||
235 | Additional PEPs of interest regarding documentation of code: |
|
168 | Additional PEPs of interest regarding documentation of code: | |
236 |
|
169 | |||
237 |
|
|
170 | * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ | |
238 |
|
|
171 | * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ | |
239 |
|
|
172 | * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ | |
240 |
|
173 | |||
241 |
|
174 | |||
242 | Coding conventions |
|
175 | Coding conventions | |
@@ -248,17 +181,16 b' General' | |||||
248 | In general, we'll try to follow the standard Python style conventions as |
|
181 | In general, we'll try to follow the standard Python style conventions as | |
249 | described here: |
|
182 | described here: | |
250 |
|
183 | |||
251 |
|
|
184 | * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_ | |
252 |
|
185 | |||
253 |
|
186 | |||
254 | Other comments: |
|
187 | Other comments: | |
255 |
|
188 | |||
256 |
|
|
189 | * In a large file, top level classes and functions should be | |
257 | separated by 2-3 lines to make it easier to separate them visually. |
|
190 | separated by 2-3 lines to make it easier to separate them visually. | |
258 |
|
|
191 | * Use 4 spaces for indentation. | |
259 |
|
|
192 | * Keep the ordering of methods the same in classes that have the same | |
260 | methods. This is particularly true for classes that implement |
|
193 | methods. This is particularly true for classes that implement an interface. | |
261 | similar interfaces and for interfaces that are similar. |
|
|||
262 |
|
194 | |||
263 | Naming conventions |
|
195 | Naming conventions | |
264 | ------------------ |
|
196 | ------------------ | |
@@ -268,38 +200,33 b' Guide for Python Code`_.' | |||||
268 |
|
200 | |||
269 | For all new IPython code (and much existing code is being refactored), we'll use: |
|
201 | For all new IPython code (and much existing code is being refactored), we'll use: | |
270 |
|
202 | |||
271 |
|
|
203 | * All ``lowercase`` module names. | |
272 |
|
204 | |||
273 |
|
|
205 | * ``CamelCase`` for class names. | |
274 |
|
206 | |||
275 |
|
|
207 | * ``lowercase_with_underscores`` for methods, functions, variables and | |
276 | attributes. |
|
208 | attributes. | |
277 |
|
209 | |||
278 | This may be confusing as most of the existing IPython codebase uses a different |
|
210 | There are, however, some important exceptions to these rules. In some cases, | |
279 | convention (``lowerCamelCase`` for methods and attributes). Slowly, we will |
|
|||
280 | move IPython over to the new convention, providing shadow names for backward |
|
|||
281 | compatibility in public interfaces. |
|
|||
282 |
|
||||
283 | There are, however, some important exceptions to these rules. In some cases, |
|
|||
284 | IPython code will interface with packages (Twisted, Wx, Qt) that use other |
|
211 | IPython code will interface with packages (Twisted, Wx, Qt) that use other | |
285 |
conventions. |
|
212 | conventions. At some level this makes it impossible to adhere to our own | |
286 |
standards at all times. |
|
213 | standards at all times. In particular, when subclassing classes that use other | |
287 |
naming conventions, you must follow their naming conventions. |
|
214 | naming conventions, you must follow their naming conventions. To deal with | |
288 | cases like this, we propose the following policy: |
|
215 | cases like this, we propose the following policy: | |
289 |
|
216 | |||
290 |
|
|
217 | * If you are subclassing a class that uses different conventions, use its | |
291 | naming conventions throughout your subclass. Thus, if you are creating a |
|
218 | naming conventions throughout your subclass. Thus, if you are creating a | |
292 | Twisted Protocol class, used Twisted's |
|
219 | Twisted Protocol class, used Twisted's | |
293 | ``namingSchemeForMethodsAndAttributes.`` |
|
220 | ``namingSchemeForMethodsAndAttributes.`` | |
294 |
|
221 | |||
295 |
|
|
222 | * All IPython's official interfaces should use our conventions. In some cases | |
296 | this will mean that you need to provide shadow names (first implement |
|
223 | this will mean that you need to provide shadow names (first implement | |
297 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all |
|
224 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all | |
298 | costs, but it will probably be necessary at times. But, please use this |
|
225 | costs, but it will probably be necessary at times. But, please use this | |
299 | sparingly! |
|
226 | sparingly! | |
300 |
|
227 | |||
301 | Implementation-specific *private* methods will use |
|
228 | Implementation-specific *private* methods will use | |
302 |
``_single_underscore_prefix``. |
|
229 | ``_single_underscore_prefix``. Names with a leading double underscore will | |
303 | *only* be used in special cases, as they makes subclassing difficult (such |
|
230 | *only* be used in special cases, as they makes subclassing difficult (such | |
304 | names are not easily seen by child classes). |
|
231 | names are not easily seen by child classes). | |
305 |
|
232 | |||
@@ -323,107 +250,38 b' specific ``IPY`` or ``ipy`` are preferred.' | |||||
323 | Testing system |
|
250 | Testing system | |
324 | ============== |
|
251 | ============== | |
325 |
|
252 | |||
326 |
It is extremely important that all code contributed to IPython has tests. |
|
253 | It is extremely important that all code contributed to IPython has tests. | |
327 |
should be written as unittests, doctests or as entities that the |
|
254 | Tests should be written as unittests, doctests or as entities that the Nose | |
328 |
testing package will find. Regardless of how the tests are written, we |
|
255 | [Nose]_ testing package will find. Regardless of how the tests are written, we | |
329 |
|
|
256 | will use Nose for discovering and running the tests. Nose will be required to | |
330 | the IPython test suite, but will not be required to simply use IPython. |
|
257 | run the IPython test suite, but will not be required to simply use IPython. | |
331 |
|
258 | |||
332 | .. _Nose: http://code.google.com/p/python-nose/ |
|
259 | Tests of Twisted using code need to follow two additional guidelines: | |
333 |
|
260 | |||
334 |
|
|
261 | 1. Twisted using tests should be written by subclassing the :class:`TestCase` | |
335 |
|
|
262 | class that comes with :mod:`twisted.trial.unittest`. | |
336 | done, `Nose`_ will be able to run the tests and the twisted reactor will be |
|
|||
337 | handled correctly. |
|
|||
338 |
|
263 | |||
339 | .. __: http://www.twistedmatrix.com |
|
264 | 2. All :class:`Deferred` instances that are created in the test must be | |
|
265 | properly chained and the final one *must* be the return value of the test | |||
|
266 | method. | |||
340 |
|
267 | |||
341 | Each subpackage in IPython should have its own ``tests`` directory that |
|
268 | When these two things are done, Nose will be able to run the tests and the | |
|
269 | twisted reactor will be handled correctly. | |||
|
270 | ||||
|
271 | Each subpackage in IPython should have its own :file:`tests` directory that | |||
342 | contains all of the tests for that subpackage. This allows each subpackage to |
|
272 | contains all of the tests for that subpackage. This allows each subpackage to | |
343 | be self-contained. If a subpackage has any dependencies beyond the Python |
|
273 | be self-contained. If a subpackage has any dependencies beyond the Python | |
344 | standard library, the tests for that subpackage should be skipped if the |
|
274 | standard library, the tests for that subpackage should be skipped if the | |
345 | dependencies are not found. This is very important so users don't get tests |
|
275 | dependencies are not found. This is very important so users don't get tests | |
346 | failing simply because they don't have dependencies. |
|
276 | failing simply because they don't have dependencies. | |
347 |
|
277 | |||
348 | We also need to look into use Noses ability to tag tests to allow a more |
|
278 | To run the IPython test suite, use the :command:`iptest` command that is installed with IPython:: | |
349 | modular approach of running tests. |
|
|||
350 |
|
279 | |||
351 | .. _devel_config: |
|
280 | $ iptest | |
352 |
|
281 | |||
353 | Configuration system |
|
282 | This command runs Nose with the proper options and extensions. | |
354 | ==================== |
|
|||
355 |
|
||||
356 | IPython uses `.ini`_ files for configuration purposes. This represents a huge |
|
|||
357 | improvement over the configuration system used in IPython. IPython works with |
|
|||
358 | these files using the `ConfigObj`_ package, which IPython includes as |
|
|||
359 | ``ipython1/external/configobj.py``. |
|
|||
360 |
|
||||
361 | Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of |
|
|||
362 | IPython should contain a ``config`` subdirectory that contains all of the |
|
|||
363 | configuration information for the subpackage. To see how configuration |
|
|||
364 | information is defined (along with defaults) see at the examples in |
|
|||
365 | ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how |
|
|||
366 | the configuration information is used, see examples in |
|
|||
367 | ``ipython1/kernel/scripts/ipengine.py``. |
|
|||
368 |
|
||||
369 | Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We |
|
|||
370 | are calling this new layer, ``tconfig``, as it will use a `Traits`_-like |
|
|||
371 | validation model. We won't actually use `Traits`_, but will implement |
|
|||
372 | something similar in pure Python. But, even in this new system, we will still |
|
|||
373 | use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you |
|
|||
374 | are interested in working on this part of IPython. The current prototype of |
|
|||
375 | ``tconfig`` is located in the IPython sandbox. |
|
|||
376 |
|
||||
377 | .. _.ini: http://docs.python.org/lib/module-ConfigParser.html |
|
|||
378 | .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html |
|
|||
379 | .. _Traits: http://code.enthought.com/traits/ |
|
|||
380 |
|
||||
381 |
|
||||
382 | Installation and testing scenarios |
|
|||
383 | ================================== |
|
|||
384 |
|
||||
385 | This section outlines the various scenarios that we need to test before we |
|
|||
386 | release an IPython version. These scenarios represent different ways of |
|
|||
387 | installing IPython and its dependencies. |
|
|||
388 |
|
||||
389 | Installation scenarios under Linux and OS X |
|
|||
390 | ------------------------------------------- |
|
|||
391 |
|
||||
392 | 1. Install from tarball using ``python setup.py install``. |
|
|||
393 | a. With only readline+nose dependencies installed. |
|
|||
394 | b. With all dependencies installed (readline, zope.interface, Twisted, |
|
|||
395 | foolscap, Sphinx, nose, pyOpenSSL). |
|
|||
396 |
|
||||
397 | 2. Install using easy_install. |
|
|||
398 |
|
||||
399 | a. With only readline+nose dependencies installed. |
|
|||
400 | i. Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg`` |
|
|||
401 | ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]`` |
|
|||
402 |
|
||||
403 | b. With all dependencies already installed. |
|
|||
404 |
|
||||
405 |
|
||||
406 | Installation scenarios under Win32 |
|
|||
407 | ---------------------------------- |
|
|||
408 |
|
||||
409 | 1. Install everything from .exe installers |
|
|||
410 | 2. easy_install? |
|
|||
411 |
|
||||
412 |
|
||||
413 | Tests to run for these scenarios |
|
|||
414 | -------------------------------- |
|
|||
415 |
|
||||
416 | 1. Run the full test suite. |
|
|||
417 | 2. Start a controller and engines and try a few things by hand. |
|
|||
418 | a. Using ipcluster. |
|
|||
419 | b. Using ipcontroller/ipengine by hand. |
|
|||
420 |
|
||||
421 | 3. Run a few of the parallel examples. |
|
|||
422 | 4. Try the kernel with and without security with and without PyOpenSSL |
|
|||
423 | installed. |
|
|||
424 | 5. Beat on the IPython terminal a bunch. |
|
|||
425 | 6. Make sure that furl files are being put in proper locations. |
|
|||
426 |
|
283 | |||
|
284 | .. _devel_config: | |||
427 |
|
285 | |||
428 | Release checklist |
|
286 | Release checklist | |
429 | ================= |
|
287 | ================= | |
@@ -434,9 +292,9 b' Most of the release process is automated by the :file:`release` script in the' | |||||
434 | #. Run the release script, which makes the tar.gz, eggs and Win32 .exe |
|
292 | #. Run the release script, which makes the tar.gz, eggs and Win32 .exe | |
435 | installer. It posts them to the site and registers the release with PyPI. |
|
293 | installer. It posts them to the site and registers the release with PyPI. | |
436 |
|
294 | |||
437 |
#. Updating the website with announcements and links to the updated |
|
295 | #. Updating the website with announcements and links to the updated | |
438 |
in html form. |
|
296 | changes.txt in html form. Remember to put a short note both on the news | |
439 |
and on |
|
297 | page of the site and on Launcphad. | |
440 |
|
298 | |||
441 | #. Drafting a short release announcement with i) highlights and ii) a link to |
|
299 | #. Drafting a short release announcement with i) highlights and ii) a link to | |
442 | the html changes.txt. |
|
300 | the html changes.txt. | |
@@ -444,3 +302,9 b' Most of the release process is automated by the :file:`release` script in the' | |||||
444 | #. Make sure that the released version of the docs is live on the site. |
|
302 | #. Make sure that the released version of the docs is live on the site. | |
445 |
|
303 | |||
446 | #. Celebrate! |
|
304 | #. Celebrate! | |
|
305 | ||||
|
306 | .. [Bazaar] Bazaar. http://bazaar-vcs.org/ | |||
|
307 | .. [Launchpad] Launchpad. http://www.launchpad.net/ipython | |||
|
308 | .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html | |||
|
309 | .. [Sphinx] Sphinx. http://sphinx.pocoo.org/ | |||
|
310 | .. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ |
General Comments 0
You need to be logged in to leave comments.
Login now