Show More
@@ -0,0 +1,141 b'' | |||
|
1 | ============== | |
|
2 | Coding guide | |
|
3 | ============== | |
|
4 | ||
|
5 | ||
|
6 | Coding conventions | |
|
7 | ================== | |
|
8 | ||
|
9 | In general, we'll try to follow the standard Python style conventions as | |
|
10 | described in Python's `PEP 8`_, the official Python Style Guide. | |
|
11 | ||
|
12 | .. _PEP 8: http://www.python.org/peps/pep-0008.html | |
|
13 | ||
|
14 | Other comments: | |
|
15 | ||
|
16 | - In a large file, top level classes and functions should be separated by 2-3 | |
|
17 | lines to make it easier to separate them visually. | |
|
18 | ||
|
19 | - Use 4 spaces for indentation, *never* use hard tabs. | |
|
20 | ||
|
21 | - Keep the ordering of methods the same in classes that have the same methods. | |
|
22 | This is particularly true for classes that implement similar interfaces and | |
|
23 | for interfaces that are similar. | |
|
24 | ||
|
25 | Naming conventions | |
|
26 | ------------------ | |
|
27 | ||
|
28 | In terms of naming conventions, we'll follow the guidelines of PEP 8. Some of | |
|
29 | the existing code doesn't honor this perfectly, but for all new IPython code | |
|
30 | (and much existing code is being refactored), we'll use: | |
|
31 | ||
|
32 | - All ``lowercase`` module names. | |
|
33 | ||
|
34 | - ``CamelCase`` for class names. | |
|
35 | ||
|
36 | - ``lowercase_with_underscores`` for methods, functions, variables and | |
|
37 | attributes. | |
|
38 | ||
|
39 | This may be confusing as some of the existing codebase uses a different | |
|
40 | convention (``lowerCamelCase`` for methods and attributes). Slowly, we will | |
|
41 | move IPython over to the new convention, providing shadow names for backward | |
|
42 | compatibility in public interfaces. | |
|
43 | ||
|
44 | There are, however, some important exceptions to these rules. In some cases, | |
|
45 | IPython code will interface with packages (Twisted, Wx, Qt) that use other | |
|
46 | conventions. At some level this makes it impossible to adhere to our own | |
|
47 | standards at all times. In particular, when subclassing classes that use other | |
|
48 | naming conventions, you must follow their naming conventions. To deal with | |
|
49 | cases like this, we propose the following policy: | |
|
50 | ||
|
51 | - If you are subclassing a class that uses different conventions, use its | |
|
52 | naming conventions throughout your subclass. Thus, if you are creating a | |
|
53 | Twisted Protocol class, used Twisted's | |
|
54 | ``namingSchemeForMethodsAndAttributes.`` | |
|
55 | ||
|
56 | - All IPython's official interfaces should use our conventions. In some cases | |
|
57 | this will mean that you need to provide shadow names (first implement | |
|
58 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all | |
|
59 | costs, but it will probably be necessary at times. But, please use this | |
|
60 | sparingly! | |
|
61 | ||
|
62 | Implementation-specific *private* methods will use | |
|
63 | ``_single_underscore_prefix``. Names with a leading double underscore will | |
|
64 | *only* be used in special cases, as they makes subclassing difficult (such | |
|
65 | names are not easily seen by child classes). | |
|
66 | ||
|
67 | Occasionally some run-in lowercase names are used, but mostly for very short | |
|
68 | names or where we are implementing methods very similar to existing ones in a | |
|
69 | base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had | |
|
70 | established precedent). | |
|
71 | ||
|
72 | The old IPython codebase has a big mix of classes and modules prefixed with an | |
|
73 | explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned | |
|
74 | upon, as namespaces offer cleaner prefixing. The only case where this approach | |
|
75 | is justified is for classes which are expected to be imported into external | |
|
76 | namespaces and a very generic name (like Shell) is too likely to clash with | |
|
77 | something else. We'll need to revisit this issue as we clean up and refactor | |
|
78 | the code, but in general we should remove as many unnecessary ``IP``/``ip`` | |
|
79 | prefixes as possible. However, if a prefix seems absolutely necessary the more | |
|
80 | specific ``IPY`` or ``ipy`` are preferred. | |
|
81 | ||
|
82 | ||
|
83 | .. _devel-testing: | |
|
84 | ||
|
85 | Testing system | |
|
86 | ============== | |
|
87 | ||
|
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/ |
@@ -0,0 +1,76 b'' | |||
|
1 | Documenting IPython | |
|
2 | =================== | |
|
3 | ||
|
4 | Standalone documentation | |
|
5 | ------------------------ | |
|
6 | ||
|
7 | All standalone documentation should be written in plain text (``.txt``) files | |
|
8 | using `reStructuredText`_ for markup and formatting. All such documentation | |
|
9 | should be placed in the top level directory ``docs`` of the IPython source | |
|
10 | tree. Or, when appropriate, a suitably named subdirectory should be used. The | |
|
11 | documentation in this location will serve as the main source for IPython | |
|
12 | documentation and all existing documentation should be converted to this | |
|
13 | format. | |
|
14 | ||
|
15 | In the future, the text files in the ``docs`` directory will be used to | |
|
16 | generate all forms of documentation for IPython. This include documentation on | |
|
17 | the IPython website as well as *pdf* documentation. | |
|
18 | ||
|
19 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
|
20 | ||
|
21 | A bit of shell code: | |
|
22 | ||
|
23 | .. code-block:: bash | |
|
24 | ||
|
25 | cd /tmp | |
|
26 | echo "My home directory is: $HOME" | |
|
27 | ls | |
|
28 | ||
|
29 | A bit of Python code: | |
|
30 | ||
|
31 | .. code-block:: python | |
|
32 | ||
|
33 | for i in range(10): | |
|
34 | print i, | |
|
35 | print "A big number:",2**34 | |
|
36 | ||
|
37 | An interactive Python session: | |
|
38 | ||
|
39 | .. code-block:: python | |
|
40 | ||
|
41 | >>> from IPython import genutils | |
|
42 | >>> genutils.get_ipython_dir() | |
|
43 | '/home/fperez/.ipython' | |
|
44 | ||
|
45 | ||
|
46 | An IPython session: | |
|
47 | ||
|
48 | .. code-block:: ipython | |
|
49 | ||
|
50 | In [8]: import IPython | |
|
51 | ||
|
52 | In [9]: print "This IPython is version:",IPython.__version__ | |
|
53 | This IPython is version: 0.9.1 | |
|
54 | ||
|
55 | ||
|
56 | ||
|
57 | Docstring format | |
|
58 | ---------------- | |
|
59 | ||
|
60 | Good docstrings are very important. All new code will use `Epydoc`_ for | |
|
61 | generating API docs, so we will follow the `Epydoc`_ conventions. More | |
|
62 | specifically, we will use `reStructuredText`_ for markup and formatting, since | |
|
63 | it is understood by a wide variety of tools. This means that if in the future | |
|
64 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer | |
|
65 | transition pains. | |
|
66 | ||
|
67 | Details about using `reStructuredText`_ for docstrings can be found `here | |
|
68 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. | |
|
69 | ||
|
70 | .. _Epydoc: http://epydoc.sourceforge.net/ | |
|
71 | ||
|
72 | Additional PEPs of interest regarding documentation of code: | |
|
73 | ||
|
74 | - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ | |
|
75 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ | |
|
76 | - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ |
@@ -1,10 +1,13 b'' | |||
|
1 | ================== | |
|
2 | Development | |
|
3 | ================== | |
|
1 | =========================== | |
|
2 | IPython Developer's Guide | |
|
3 | =========================== | |
|
4 | 4 | |
|
5 | 5 | .. toctree:: |
|
6 | 6 | :maxdepth: 2 |
|
7 | 7 | |
|
8 |
|
|
|
8 | overview.txt | |
|
9 | coding_guide.txt | |
|
10 | doc_guide.txt | |
|
9 | 11 | roadmap.txt |
|
12 | ||
|
10 | 13 | notification_blueprint.txt |
@@ -1,16 +1,16 b'' | |||
|
1 | .. This file has a lot of bash but little python, set default role | |
|
2 | ||
|
3 | .. highlight:: bash | |
|
4 | ||
|
1 | 5 | .. _development: |
|
2 | 6 | |
|
3 | 7 | ============================== |
|
4 |
IPython development |
|
|
8 | IPython development overview | |
|
5 | 9 | ============================== |
|
6 | 10 | |
|
7 | ||
|
8 | Overview | |
|
9 | ======== | |
|
10 | ||
|
11 | 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 |
that was known for a while (roughly 2004-2008) as `IPython1 |
|
|
13 | that was known for a while (roughly 2004-2008) as ``IPython1``. The IPyhton1 | |
|
14 | 14 | development was meant to be an effort to: |
|
15 | 15 | |
|
16 | 16 | 1. Clean up the existing codebase and write lots of tests. |
@@ -23,8 +23,13 b' development was meant to be an effort to:' | |||
|
23 | 23 | While the third goal may seem a bit unrelated to the main focus of IPython, it |
|
24 | 24 | turns out that the technologies required for this goal are nearly identical |
|
25 | 25 | with those required for goal two. This is the main reason the interactive |
|
26 |
parallel computing capabilities are being put into IPython proper. |
|
|
27 | the third of these goals is furthest along. | |
|
26 | parallel computing capabilities are being put into IPython proper. | |
|
27 | ||
|
28 | In the summer of 2008, the IPython1 code was merged back into the mainline, and | |
|
29 | now there is a unified codebase. While the above goals aren't completely | |
|
30 | implemented for the older code, we do have a proper :ref:`testing system | |
|
31 | <devel-testing>` in place (though this is still evolving), unified | |
|
32 | documentation and partial implementations of the more separated components. | |
|
28 | 33 | |
|
29 | 34 | This document describes IPython from the perspective of developers. |
|
30 | 35 | |
@@ -44,12 +49,14 b' subpackages will have its own:' | |||
|
44 | 49 | |
|
45 | 50 | - **Tests**. Each subpackage shoud have its own ``tests`` subdirectory that |
|
46 | 51 | contains all of the tests for that package. For information about writing |
|
47 |
tests for IPython, see the `Testing System` |
|
|
52 | tests for IPython, see the :ref:`Testing System <devel-testing>` section of | |
|
53 | this document. | |
|
48 | 54 | |
|
49 | 55 | - **Configuration**. Each subpackage should have its own ``config`` |
|
50 | 56 | subdirectory that contains the configuration information for the components |
|
51 | 57 | of the subpackage. For information about how the IPython configuration |
|
52 |
system works, see the `Configuration System` |
|
|
58 | system works, see the :ref:`Configuration System <devel-config>` section of | |
|
59 | this document. | |
|
53 | 60 | |
|
54 | 61 | - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory |
|
55 | 62 | that contains all of the command line scripts associated with the subpackage. |
@@ -116,15 +123,12 b' Specific subpackages' | |||
|
116 | 123 | today 's IPython. Other frontends will likely be more powerful and based |
|
117 | 124 | on GUI toolkits. |
|
118 | 125 | |
|
119 | ``notebook`` | |
|
120 | An application that allows users to work with IPython notebooks. | |
|
121 | ||
|
122 | 126 | ``tools`` |
|
123 | 127 | This is where general utilities go. |
|
124 | 128 | |
|
125 | 129 | |
|
126 | Version control | |
|
127 | =============== | |
|
130 | Version control workflow | |
|
131 | ======================== | |
|
128 | 132 | |
|
129 | 133 | All IPython development today is done using the `Bazaar`__ system for |
|
130 | 134 | distributed version control and the `Launchpad`__ site for code hosting and bug |
@@ -140,9 +144,7 b" for IPython you'll eventually want to have a Launchpad account (free) so you" | |||
|
140 | 144 | can publish your own code on the site for review and merging, but small |
|
141 | 145 | contributions can be simply sent via email to the IPython list as patches. |
|
142 | 146 | |
|
143 | Start by creating what Bazaar calls a `shared repository`_: | |
|
144 | ||
|
145 | .. sourcecode:: bash | |
|
147 | Start by creating what Bazaar calls a `shared repository`_:: | |
|
146 | 148 | |
|
147 | 149 | # You can choose any name you want instead of "ipython-repo" |
|
148 | 150 | bzr init-repo ipython-repo |
@@ -152,9 +154,7 b' Start by creating what Bazaar calls a `shared repository`_:' | |||
|
152 | 154 | This creates an empty repository where a lot of related branches can be kept, |
|
153 | 155 | and they all reuse common storage. This way, many operations are very fast and |
|
154 | 156 | take up less space. Now, go to the newly created repository and make a local |
|
155 | branch of the public trunk: | |
|
156 | ||
|
157 | .. sourcecode:: bash | |
|
157 | branch of the public trunk:: | |
|
158 | 158 | |
|
159 | 159 | cd ipython-repo |
|
160 | 160 | # This makes a local copy of the public trunk called "trunk-lp" |
@@ -162,9 +162,7 b' branch of the public trunk:' | |||
|
162 | 162 | |
|
163 | 163 | The ``trunk-lp`` branch is meant to always be a pristine copy of the public |
|
164 | 164 | trunk. From here, make a personal development copy of the public trunk, where |
|
165 | you'll make your changes: | |
|
166 | ||
|
167 | .. sourcecode:: bash | |
|
165 | you'll make your changes:: | |
|
168 | 166 | |
|
169 | 167 | bzr branch trunk-lp trunk-dev |
|
170 | 168 | |
@@ -180,9 +178,7 b' is to make branches to contain specific feature implementations until they are' | |||
|
180 | 178 | ready to be merged). |
|
181 | 179 | |
|
182 | 180 | The typical work cycle will be to make changes in ``trunk-dev`` and then commit |
|
183 | those changes as often as needed: | |
|
184 | ||
|
185 | .. sourcecode:: bash | |
|
181 | those changes as often as needed:: | |
|
186 | 182 | |
|
187 | 183 | cd trunk-dev |
|
188 | 184 | # ... implement cool new feature... |
@@ -207,17 +203,13 b' atomic change, the bzr log should give an excellent view of the project, and' | |||
|
207 | 203 | the ``--short`` log option becomes a nice summary. |
|
208 | 204 | |
|
209 | 205 | 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: | |
|
211 | ||
|
212 | .. sourcecode:: bash | |
|
206 | trunk updated with respect to Launchpad. This is done via:: | |
|
213 | 207 | |
|
214 | 208 | cd trunk-lp |
|
215 | 209 | bzr pull |
|
216 | 210 | |
|
217 | 211 | Bazaar can then merge any changes that were done to the public trunk into your |
|
218 | local branch via: | |
|
219 | ||
|
220 | .. sourcecode:: bash | |
|
212 | local branch via:: | |
|
221 | 213 | |
|
222 | 214 | cd trunk-dev |
|
223 | 215 | bzr merge ../trunk-lp |
@@ -227,16 +219,13 b' This workflow ensures that a local copy stays in sync with the public trunk,' | |||
|
227 | 219 | while allowing for local development to be pushed back for public review. |
|
228 | 220 | |
|
229 | 221 | Once your changes are ready for review, you can push them to Launchpad where |
|
230 | the IPython team can review them and give you feedback. The first time, use: | |
|
222 | the IPython team can review them and give you feedback. The first time, use:: | |
|
231 | 223 | |
|
232 | .. sourcecode:: bash | |
|
233 | ||
|
234 | bzr push --remember bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev | |
|
224 | bzr push --remember \ | |
|
225 | bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev | |
|
235 | 226 | |
|
236 | 227 | 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: | |
|
238 | ||
|
239 | .. sourcecode:: bash | |
|
228 | publicly visible to all. In subsequent uses you can simply run in the branch:: | |
|
240 | 229 | |
|
241 | 230 | bzr push |
|
242 | 231 | |
@@ -249,10 +238,10 b' publicly visible to all. In subsequent uses you can simply run in the branch:' | |||
|
249 | 238 | on how to upload your keys. |
|
250 | 239 | |
|
251 | 240 | Once the branch is publicly visible, using the launchpad interface it can be |
|
252 |
marked for merging with the link |
|
|
253 |
leaving the default choice of trunk as its target. This way, |
|
|
254 |
what changes of this branch are new with respect to the trunk, |
|
|
255 | team can review it, and merge the changes into the trunk. | |
|
241 | marked for merging with the link marked *"Propose for merging into another | |
|
242 | branch"*, leaving the default choice of trunk as its target. This way, | |
|
243 | Launchpad tracks what changes of this branch are new with respect to the trunk, | |
|
244 | others in the team can review it, and merge the changes into the trunk. | |
|
256 | 245 | |
|
257 | 246 | The IPython team has a policy of reviewing all code (both from core members of |
|
258 | 247 | the team and from external contributors) before merging it. Code should be |
@@ -262,226 +251,6 b" contribution to the project, and we've found that peer review of code is an" | |||
|
262 | 251 | excellent way to improve the quality of everyone's work. |
|
263 | 252 | |
|
264 | 253 | |
|
265 | Coding conventions | |
|
266 | ================== | |
|
267 | ||
|
268 | General | |
|
269 | ------- | |
|
270 | ||
|
271 | In general, we'll try to follow the standard Python style conventions as | |
|
272 | described here: | |
|
273 | ||
|
274 | - `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_ | |
|
275 | ||
|
276 | ||
|
277 | Other comments: | |
|
278 | ||
|
279 | - In a large file, top level classes and functions should be | |
|
280 | separated by 2-3 lines to make it easier to separate them visually. | |
|
281 | - Use 4 spaces for indentation. | |
|
282 | - Keep the ordering of methods the same in classes that have the same | |
|
283 | methods. This is particularly true for classes that implement | |
|
284 | similar interfaces and for interfaces that are similar. | |
|
285 | ||
|
286 | Naming conventions | |
|
287 | ------------------ | |
|
288 | ||
|
289 | In terms of naming conventions, we'll follow the guidelines from the `Style | |
|
290 | Guide for Python Code`_. | |
|
291 | ||
|
292 | For all new IPython code (and much existing code is being refactored), we'll use: | |
|
293 | ||
|
294 | - All ``lowercase`` module names. | |
|
295 | ||
|
296 | - ``CamelCase`` for class names. | |
|
297 | ||
|
298 | - ``lowercase_with_underscores`` for methods, functions, variables and | |
|
299 | attributes. | |
|
300 | ||
|
301 | This may be confusing as most of the existing IPython codebase uses a different | |
|
302 | convention (``lowerCamelCase`` for methods and attributes). Slowly, we will | |
|
303 | move IPython over to the new convention, providing shadow names for backward | |
|
304 | compatibility in public interfaces. | |
|
305 | ||
|
306 | There are, however, some important exceptions to these rules. In some cases, | |
|
307 | IPython code will interface with packages (Twisted, Wx, Qt) that use other | |
|
308 | conventions. At some level this makes it impossible to adhere to our own | |
|
309 | standards at all times. In particular, when subclassing classes that use other | |
|
310 | naming conventions, you must follow their naming conventions. To deal with | |
|
311 | cases like this, we propose the following policy: | |
|
312 | ||
|
313 | - If you are subclassing a class that uses different conventions, use its | |
|
314 | naming conventions throughout your subclass. Thus, if you are creating a | |
|
315 | Twisted Protocol class, used Twisted's | |
|
316 | ``namingSchemeForMethodsAndAttributes.`` | |
|
317 | ||
|
318 | - All IPython's official interfaces should use our conventions. In some cases | |
|
319 | this will mean that you need to provide shadow names (first implement | |
|
320 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all | |
|
321 | costs, but it will probably be necessary at times. But, please use this | |
|
322 | sparingly! | |
|
323 | ||
|
324 | Implementation-specific *private* methods will use | |
|
325 | ``_single_underscore_prefix``. Names with a leading double underscore will | |
|
326 | *only* be used in special cases, as they makes subclassing difficult (such | |
|
327 | names are not easily seen by child classes). | |
|
328 | ||
|
329 | Occasionally some run-in lowercase names are used, but mostly for very short | |
|
330 | names or where we are implementing methods very similar to existing ones in a | |
|
331 | base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had | |
|
332 | established precedent). | |
|
333 | ||
|
334 | The old IPython codebase has a big mix of classes and modules prefixed with an | |
|
335 | explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned | |
|
336 | upon, as namespaces offer cleaner prefixing. The only case where this approach | |
|
337 | is justified is for classes which are expected to be imported into external | |
|
338 | namespaces and a very generic name (like Shell) is too likely to clash with | |
|
339 | something else. We'll need to revisit this issue as we clean up and refactor | |
|
340 | the code, but in general we should remove as many unnecessary ``IP``/``ip`` | |
|
341 | prefixes as possible. However, if a prefix seems absolutely necessary the more | |
|
342 | specific ``IPY`` or ``ipy`` are preferred. | |
|
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 | ||
|
424 | .. _devel_testing: | |
|
425 | ||
|
426 | Testing system | |
|
427 | ============== | |
|
428 | ||
|
429 | It is extremely important that all code contributed to IPython has tests. Tests | |
|
430 | should be written as unittests, doctests or as entities that the `Nose`_ | |
|
431 | testing package will find. Regardless of how the tests are written, we will use | |
|
432 | `Nose`_ for discovering and running the tests. `Nose`_ will be required to run | |
|
433 | the IPython test suite, but will not be required to simply use IPython. | |
|
434 | ||
|
435 | .. _Nose: http://code.google.com/p/python-nose/ | |
|
436 | ||
|
437 | Tests of `Twisted`__ using code should be written by subclassing the | |
|
438 | ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is | |
|
439 | done, `Nose`_ will be able to run the tests and the twisted reactor will be | |
|
440 | handled correctly. | |
|
441 | ||
|
442 | .. __: http://www.twistedmatrix.com | |
|
443 | ||
|
444 | Each subpackage in IPython should have its own ``tests`` directory that | |
|
445 | contains all of the tests for that subpackage. This allows each subpackage to | |
|
446 | be self-contained. If a subpackage has any dependencies beyond the Python | |
|
447 | standard library, the tests for that subpackage should be skipped if the | |
|
448 | dependencies are not found. This is very important so users don't get tests | |
|
449 | failing simply because they don't have dependencies. | |
|
450 | ||
|
451 | We also need to look into use Noses ability to tag tests to allow a more | |
|
452 | modular approach of running tests. | |
|
453 | ||
|
454 | .. _devel_config: | |
|
455 | ||
|
456 | Configuration system | |
|
457 | ==================== | |
|
458 | ||
|
459 | IPython uses `.ini`_ files for configuration purposes. This represents a huge | |
|
460 | improvement over the configuration system used in IPython. IPython works with | |
|
461 | these files using the `ConfigObj`_ package, which IPython includes as | |
|
462 | ``ipython1/external/configobj.py``. | |
|
463 | ||
|
464 | Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of | |
|
465 | IPython should contain a ``config`` subdirectory that contains all of the | |
|
466 | configuration information for the subpackage. To see how configuration | |
|
467 | information is defined (along with defaults) see at the examples in | |
|
468 | ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how | |
|
469 | the configuration information is used, see examples in | |
|
470 | ``ipython1/kernel/scripts/ipengine.py``. | |
|
471 | ||
|
472 | Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We | |
|
473 | are calling this new layer, ``tconfig``, as it will use a `Traits`_-like | |
|
474 | validation model. We won't actually use `Traits`_, but will implement | |
|
475 | something similar in pure Python. But, even in this new system, we will still | |
|
476 | use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you | |
|
477 | are interested in working on this part of IPython. The current prototype of | |
|
478 | ``tconfig`` is located in the IPython sandbox. | |
|
479 | ||
|
480 | .. _.ini: http://docs.python.org/lib/module-ConfigParser.html | |
|
481 | .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html | |
|
482 | .. _Traits: http://code.enthought.com/traits/ | |
|
483 | ||
|
484 | ||
|
485 | 254 | Installation and testing scenarios |
|
486 | 255 | ================================== |
|
487 | 256 | |
@@ -489,43 +258,54 b' This section outlines the various scenarios that we need to test before we' | |||
|
489 | 258 | release an IPython version. These scenarios represent different ways of |
|
490 | 259 | installing IPython and its dependencies. |
|
491 | 260 | |
|
261 | ||
|
492 | 262 | Installation scenarios under Linux and OS X |
|
493 | 263 | ------------------------------------------- |
|
494 | 264 | |
|
495 |
|
|
|
496 | a. With only readline+nose dependencies installed. | |
|
497 | b. With all dependencies installed (readline, zope.interface, Twisted, | |
|
498 | foolscap, Sphinx, nose, pyOpenSSL). | |
|
499 | ||
|
500 | 2. Install using easy_install. | |
|
265 | 1. Install from tarball using ``python setup.py install``. | |
|
266 | ||
|
267 | * With only readline+nose dependencies installed. | |
|
268 | ||
|
269 | * With all dependencies installed (readline, zope.interface, Twisted, | |
|
270 | foolscap, Sphinx, nose, pyOpenSSL). | |
|
271 | ||
|
272 | 2. Install using easy_install. | |
|
273 | ||
|
274 | * With only readline+nose dependencies installed. | |
|
275 | ||
|
276 | * Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg`` | |
|
501 | 277 | |
|
502 | a. With only readline+nose dependencies installed. | |
|
503 | i. Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg`` | |
|
504 | ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]`` | |
|
278 | * Optional dependency sets: | |
|
279 | ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]`` | |
|
505 | 280 | |
|
506 |
|
|
|
281 | * With all dependencies already installed. | |
|
507 | 282 | |
|
508 | 283 | |
|
509 | 284 | Installation scenarios under Win32 |
|
510 | 285 | ---------------------------------- |
|
511 | 286 | |
|
512 |
|
|
|
513 |
|
|
|
287 | #. Install everything from .exe installers | |
|
288 | #. easy_install? | |
|
514 | 289 | |
|
515 | 290 | |
|
516 | 291 | Tests to run for these scenarios |
|
517 | 292 | -------------------------------- |
|
518 | 293 | |
|
519 |
|
|
|
520 | 2. Start a controller and engines and try a few things by hand. | |
|
521 | a. Using ipcluster. | |
|
522 | b. Using ipcontroller/ipengine by hand. | |
|
294 | #. Run the full test suite. | |
|
295 | ||
|
296 | #. Start a controller and engines and try a few things by hand. | |
|
297 | ||
|
298 | * Using ipcluster. | |
|
299 | * Using ipcontroller/ipengine by hand. | |
|
300 | ||
|
301 | #. Run a few of the parallel examples. | |
|
302 | ||
|
303 | #. Try the kernel with and without security with and without PyOpenSSL | |
|
304 | installed. | |
|
305 | ||
|
306 | #. Beat on the IPython terminal a bunch. | |
|
523 | 307 | |
|
524 | 3. Run a few of the parallel examples. | |
|
525 | 4. Try the kernel with and without security with and without PyOpenSSL | |
|
526 | installed. | |
|
527 | 5. Beat on the IPython terminal a bunch. | |
|
528 | 6. Make sure that furl files are being put in proper locations. | |
|
308 | #. Make sure that furl files are being put in proper locations. | |
|
529 | 309 | |
|
530 | 310 | |
|
531 | 311 | Release checklist |
@@ -1,3 +1,7 b'' | |||
|
1 | .. There's little Python in this file, so make the default language bash. | |
|
2 | ||
|
3 | .. highlight:: bash | |
|
4 | ||
|
1 | 5 | Overview |
|
2 | 6 | ======== |
|
3 | 7 | |
@@ -42,31 +46,25 b' Installation using easy_install' | |||
|
42 | 46 | ------------------------------- |
|
43 | 47 | |
|
44 | 48 | If you have :mod:`setuptools` installed, the easiest way of getting IPython is |
|
45 | to use :command:`easy_install`: | |
|
46 | ||
|
47 | .. sourcecode:: bash | |
|
49 | to use :command:`easy_install`:: | |
|
48 | 50 | |
|
49 | 51 | easy_install IPython |
|
50 | 52 | |
|
51 | Unless you've written a custom distutils script as explained here_, that will | |
|
53 | Unless you've written a custom distutils script as explained `here`__, that will | |
|
52 | 54 | try to install either in a default system-wide location, which may require |
|
53 | 55 | administrator access. If that is the case, you can either run the command with |
|
54 | root privileges: | |
|
55 | ||
|
56 | .. sourcecode:: bash | |
|
56 | root privileges:: | |
|
57 | 57 | |
|
58 | 58 | sudo easy_install IPython |
|
59 | 59 | |
|
60 | or you can specify an alternate location, for example: | |
|
61 | ||
|
62 | .. sourcecode:: bash | |
|
60 | or you can specify an alternate location, for example:: | |
|
63 | 61 | |
|
64 | 62 | easy_install --prefix=~/usr/local IPython |
|
65 | 63 | |
|
66 | 64 | where this assumes that ``~/usr/local`` is a valid prefix for you to install |
|
67 | 65 | packages to in your user account. |
|
68 | 66 | |
|
69 |
.. _ |
|
|
67 | .. __: http://docs.python.org/install/index.html#inst-config-files | |
|
70 | 68 | |
|
71 | 69 | |
|
72 | 70 | Installation from source |
@@ -75,9 +73,7 b' Installation from source' | |||
|
75 | 73 | If you don't want to use :command:`easy_install`, or don't have it installed, |
|
76 | 74 | just grab the latest stable build of IPython from `here |
|
77 | 75 | <http://ipython.scipy.org/dist/>`_. Then do the following (using the |
|
78 | appropriate version number): | |
|
79 | ||
|
80 | .. sourcecode:: bash | |
|
76 | appropriate version number):: | |
|
81 | 77 | |
|
82 | 78 | tar -xzf ipython.tar.gz |
|
83 | 79 | cd ipython |
@@ -91,11 +87,13 b' Windows' | |||
|
91 | 87 | |
|
92 | 88 | There are a few caveats for Windows users. The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want. To get an installation with these, there are two choices: |
|
93 | 89 | |
|
94 |
|
|
|
90 | #. Install using :command:`easy_install`. | |
|
95 | 91 | |
|
96 |
|
|
|
92 | #. Install using our binary ``.exe`` Windows installer, which can be found at | |
|
93 | `here <http://ipython.scipy.org/dist/>`_ | |
|
97 | 94 | |
|
98 |
|
|
|
95 | #. Install from source, but using :mod:`setuptools` (``python setupegg.py | |
|
96 | install``). | |
|
99 | 97 | |
|
100 | 98 | Installing the development version |
|
101 | 99 | ---------------------------------- |
@@ -104,8 +102,6 b' It is also possible to install the development version of IPython from our' | |||
|
104 | 102 | `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will |
|
105 | 103 | need to have Bazaar installed on your system. Then just do:: |
|
106 | 104 | |
|
107 | .. sourcecode:: bash | |
|
108 | ||
|
109 | 105 | bzr branch lp:ipython |
|
110 | 106 | cd ipython |
|
111 | 107 | python setup.py install |
@@ -114,18 +110,17 b" Again, this last step on Windows won't create ``.bat`` files or Start Menu short" | |||
|
114 | 110 | |
|
115 | 111 | Some users want to be able to follow the development branch as it changes. If |
|
116 | 112 | you have :mod:`setuptools` installed, this is easy. Simply replace the last |
|
117 | step by: | |
|
118 | ||
|
119 | .. sourcecode:: bash | |
|
113 | step by:: | |
|
120 | 114 | |
|
121 | 115 | python setupegg.py develop |
|
122 | 116 | |
|
123 |
This creates links in the right places and installs the command line script to |
|
|
124 | ||
|
125 | .. sourcecode:: bash | |
|
117 | This creates links in the right places and installs the command line script to | |
|
118 | the appropriate places. Then, if you want to update your IPython at any time, | |
|
119 | just do:: | |
|
126 | 120 | |
|
127 | 121 | bzr pull |
|
128 | 122 | |
|
123 | ||
|
129 | 124 | Basic optional dependencies |
|
130 | 125 | =========================== |
|
131 | 126 | |
@@ -140,7 +135,9 b' If you are comfortable installing these things yourself, have at it, otherwise r' | |||
|
140 | 135 | readline |
|
141 | 136 | -------- |
|
142 | 137 | |
|
143 | In principle, all Python distributions should come with a working :mod:`readline` module. But, reality is not quite that simple. There are two common situations where you won't have a working :mod:`readline` module: | |
|
138 | In principle, all Python distributions should come with a working | |
|
139 | :mod:`readline` module. But, reality is not quite that simple. There are two | |
|
140 | common situations where you won't have a working :mod:`readline` module: | |
|
144 | 141 | |
|
145 | 142 | * If you are using the built-in Python on Mac OS X. |
|
146 | 143 | |
@@ -153,9 +150,7 b' many of the issues related to the differences between readline and libedit have' | |||
|
153 | 150 | been resolved. For many users, libedit may be sufficient. |
|
154 | 151 | |
|
155 | 152 | 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): | |
|
157 | ||
|
158 | .. sourcecode:: bash | |
|
153 | working :mod:`readline` module, just do (with :mod:`setuptools` installed):: | |
|
159 | 154 | |
|
160 | 155 | easy_install readline |
|
161 | 156 | |
@@ -181,23 +176,17 b' nose' | |||
|
181 | 176 | |
|
182 | 177 | To run the IPython test suite you will need the :mod:`nose` package. Nose |
|
183 | 178 | 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 | |
|
179 | simplest way of getting nose, is to use :command:`easy_install`:: | |
|
187 | 180 | |
|
188 | 181 | easy_install nose |
|
189 | 182 | |
|
190 | Another way of getting this is to do: | |
|
191 | ||
|
192 | .. sourcecode:: bash | |
|
183 | Another way of getting this is to do:: | |
|
193 | 184 | |
|
194 | 185 | easy_install IPython[test] |
|
195 | 186 | |
|
196 | 187 | For more installation options, see the `nose website |
|
197 | 188 | <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 | |
|
189 | installed, you can run IPython's test suite using the iptest command:: | |
|
201 | 190 | |
|
202 | 191 | iptest |
|
203 | 192 | |
@@ -206,9 +195,7 b' pexpect' | |||
|
206 | 195 | ------- |
|
207 | 196 | |
|
208 | 197 | 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 | |
|
198 | :command:`irunner` script. On Unix platforms (including OS X), just do:: | |
|
212 | 199 | |
|
213 | 200 | easy_install pexpect |
|
214 | 201 | |
@@ -227,9 +214,7 b' features require a number of additional packages:' | |||
|
227 | 214 | * pyOpenSSL (security for network connections) |
|
228 | 215 | |
|
229 | 216 | On a Unix style platform (including OS X), if you want to use |
|
230 | :mod:`setuptools`, you can just do: | |
|
231 | ||
|
232 | .. sourcecode:: bash | |
|
217 | :mod:`setuptools`, you can just do:: | |
|
233 | 218 | |
|
234 | 219 | easy_install IPython[kernel] # the first three |
|
235 | 220 | easy_install IPython[security] # pyOpenSSL |
@@ -238,9 +223,7 b' zope.interface and Twisted' | |||
|
238 | 223 | -------------------------- |
|
239 | 224 | |
|
240 | 225 | 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 | |
|
226 | is to use :command:`easy_install`:: | |
|
244 | 227 | |
|
245 | 228 | easy_install zope.interface |
|
246 | 229 | easy_install Twisted |
@@ -260,9 +243,7 b' Foolscap' | |||
|
260 | 243 | Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to |
|
261 | 244 | implement our parallel computing features. |
|
262 | 245 | |
|
263 | On all platforms a simple: | |
|
264 | ||
|
265 | .. sourcecode:: bash | |
|
246 | On all platforms a simple:: | |
|
266 | 247 | |
|
267 | 248 | easy_install foolscap |
|
268 | 249 | |
@@ -297,4 +278,4 b' a nice wxPython based IPython GUI. As you would expect, this GUI requires' | |||
|
297 | 278 | wxPython. Most Linux distributions have wxPython packages available and the |
|
298 | 279 | built-in Python on OS X comes with wxPython preinstalled. For Windows, a |
|
299 | 280 | binary installer is available on the `wxPython website |
|
300 | <http://www.wxpython.org/>`_. No newline at end of file | |
|
281 | <http://www.wxpython.org/>`_. |
General Comments 0
You need to be logged in to leave comments.
Login now