Show More
@@ -1,226 +1,228 b'' | |||||
1 | ============================= |
|
1 | ============================= | |
2 | IPython module reorganization |
|
2 | IPython module reorganization | |
3 | ============================= |
|
3 | ============================= | |
4 |
|
4 | |||
5 | Currently, IPython has many top-level modules that serve many different purposes. |
|
5 | Currently, IPython has many top-level modules that serve many different purposes. | |
6 | The lack of organization make it very difficult for developers to work on IPython |
|
6 | The lack of organization make it very difficult for developers to work on IPython | |
7 | and understand its design. This document contains notes about how we will reorganize |
|
7 | and understand its design. This document contains notes about how we will reorganize | |
8 | the modules into sub-packages. |
|
8 | the modules into sub-packages. | |
9 |
|
9 | |||
10 | .. warning:: |
|
10 | .. warning:: | |
11 |
|
11 | |||
12 | This effort will possibly break third party packages that use IPython as |
|
12 | This effort will possibly break third party packages that use IPython as | |
13 | a library or hack on the IPython internals. |
|
13 | a library or hack on the IPython internals. | |
14 |
|
14 | |||
15 | .. warning:: |
|
15 | .. warning:: | |
16 |
|
16 | |||
17 | This effort will result in the removal from IPython of certain modules |
|
17 | This effort will result in the removal from IPython of certain modules | |
18 | that are not used anymore, don't currently work, are unmaintained, etc. |
|
18 | that are not used anymore, don't currently work, are unmaintained, etc. | |
19 |
|
19 | |||
20 |
|
20 | |||
21 | Current subpackges |
|
21 | Current subpackges | |
22 | ================== |
|
22 | ================== | |
23 |
|
23 | |||
24 | IPython currently has the following sub-packages: |
|
24 | IPython currently has the following sub-packages: | |
25 |
|
25 | |||
26 | * :mod:`IPython.config` |
|
26 | * :mod:`IPython.config` | |
27 |
|
27 | |||
28 | * :mod:`IPython.Extensions` |
|
28 | * :mod:`IPython.Extensions` | |
29 |
|
29 | |||
30 | * :mod:`IPython.external` |
|
30 | * :mod:`IPython.external` | |
31 |
|
31 | |||
32 | * :mod:`IPython.frontend` |
|
32 | * :mod:`IPython.frontend` | |
33 |
|
33 | |||
34 | * :mod:`IPython.gui` |
|
34 | * :mod:`IPython.gui` | |
35 |
|
35 | |||
36 | * :mod:`IPython.kernel` |
|
36 | * :mod:`IPython.kernel` | |
37 |
|
37 | |||
38 | * :mod:`IPython.testing` |
|
38 | * :mod:`IPython.testing` | |
39 |
|
39 | |||
40 | * :mod:`IPython.tests` |
|
40 | * :mod:`IPython.tests` | |
41 |
|
41 | |||
42 | * :mod:`IPython.tools` |
|
42 | * :mod:`IPython.tools` | |
43 |
|
43 | |||
44 | * :mod:`IPython.UserConfig` |
|
44 | * :mod:`IPython.UserConfig` | |
45 |
|
45 | |||
46 | New Subpackages to be created |
|
46 | New Subpackages to be created | |
47 | ============================= |
|
47 | ============================= | |
48 |
|
48 | |||
49 | We propose to create the following new sub-packages: |
|
49 | We propose to create the following new sub-packages: | |
50 |
|
50 | |||
51 | * :mod:`IPython.core`. This sub-package will contain the core of the IPython |
|
51 | * :mod:`IPython.core`. This sub-package will contain the core of the IPython | |
52 | interpreter, but none of its extended capabilities. |
|
52 | interpreter, but none of its extended capabilities. | |
53 |
|
53 | |||
54 | * :mod:`IPython.lib`. IPython has many extended capabilities that are not part |
|
54 | * :mod:`IPython.lib`. IPython has many extended capabilities that are not part | |
55 | of the IPython core. These things will go here. Any better names than |
|
55 | of the IPython core. These things will go here. Any better names than | |
56 | :mod:`IPython.lib`? |
|
56 | :mod:`IPython.lib`? | |
57 |
|
57 | |||
58 |
* :mod:`IPython. |
|
58 | * :mod:`IPython.utils`. This sub-package will contain anything that might | |
59 | eventually be found in the Python standard library, like things in |
|
59 | eventually be found in the Python standard library, like things in | |
60 | :mod:`genutils`. Each sub-module in this sub-package should contain functions |
|
60 | :mod:`genutils`. Each sub-module in this sub-package should contain functions | |
61 |
and classes that serve a single purpose. |
|
61 | and classes that serve a single purpose. | |
62 | :mod:`twisted.python`. Could also call this :mod:`IPython.tools`, |
|
|||
63 | :mod:`IPython.utils` or something similar. |
|
|||
64 |
|
62 | |||
65 |
* :mod:`IPython. |
|
63 | * :mod:`IPython.deathrow`. This is for code that is untested and/or rotting | |
66 |
needs to be removed from IPython. Eventually all this code will either |
|
64 | and needs to be removed from IPython. Eventually all this code will either | |
67 | revived by someone willing to maintain it with tests and docs and |
|
65 | i) be revived by someone willing to maintain it with tests and docs and | |
68 | re-included into IPython or 2) be removed from IPython proper, but put into |
|
66 | re-included into IPython or 2) be removed from IPython proper, but put into | |
69 |
a separate top-level (not IPython) package that we keep around. |
|
67 | a separate top-level (not IPython) package that we keep around. No new code | |
70 | will be allowed here, so maybe "sandbox" is not the best name. |
|
68 | will be allowed here. | |
|
69 | ||||
|
70 | * :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's | |||
|
71 | standards, but that we plan on keeping. To be moved out of this sub-package | |||
|
72 | a module needs to have a maintainer, tests and documentation. | |||
71 |
|
73 | |||
72 | Where things will be moved |
|
74 | Where things will be moved | |
73 | ========================== |
|
75 | ========================== | |
74 |
|
76 | |||
75 | * :file:`ColorANSI.py`. Move to :file:`IPython/core/coloransi.py`. Maybe move to |
|
77 | * :file:`ColorANSI.py`. Move to :file:`IPython/core/coloransi.py`. Maybe move to | |
76 | :mod:`IPython.lib` or :mod:`IPython.python`? |
|
78 | :mod:`IPython.lib` or :mod:`IPython.python`? | |
77 |
|
79 | |||
78 | * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`. |
|
80 | * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`. | |
79 |
|
81 | |||
80 | * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`. |
|
82 | * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`. | |
81 |
|
83 | |||
82 | * :file:`DPyGetOpt.py`. Move to :mod:`IPython.sandbox` and replace with newer options parser. |
|
84 | * :file:`DPyGetOpt.py`. Move to :mod:`IPython.sandbox` and replace with newer options parser. | |
83 |
|
85 | |||
84 | * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`. |
|
86 | * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`. | |
85 |
|
87 | |||
86 | * :file:`Extensions`. This needs to be gone through separately. Minimally, |
|
88 | * :file:`Extensions`. This needs to be gone through separately. Minimally, | |
87 | the package should be renamed to :file:`extensions`. |
|
89 | the package should be renamed to :file:`extensions`. | |
88 |
|
90 | |||
89 | * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`. |
|
91 | * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`. | |
90 |
|
92 | |||
91 | * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`. |
|
93 | * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`. | |
92 |
|
94 | |||
93 | * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`. |
|
95 | * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`. | |
94 |
|
96 | |||
95 | * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`. |
|
97 | * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`. | |
96 |
|
98 | |||
97 | * :file:`Itpl.py`. Remove. Version already in :file:`IPython.external`. |
|
99 | * :file:`Itpl.py`. Remove. Version already in :file:`IPython.external`. | |
98 |
|
100 | |||
99 | * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`. |
|
101 | * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`. | |
100 |
|
102 | |||
101 | * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`. |
|
103 | * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`. | |
102 |
|
104 | |||
103 | * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`. |
|
105 | * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`. | |
104 |
|
106 | |||
105 | * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`. |
|
107 | * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`. | |
106 |
|
108 | |||
107 | * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or |
|
109 | * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or | |
108 | :file:`IPython/frontend/prompts.py`. |
|
110 | :file:`IPython/frontend/prompts.py`. | |
109 |
|
111 | |||
110 | * :file:`PyColorize.py`. Replace with pygments? If not, move to |
|
112 | * :file:`PyColorize.py`. Replace with pygments? If not, move to | |
111 | :file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or |
|
113 | :file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or | |
112 | :mod:`IPython.python`? |
|
114 | :mod:`IPython.python`? | |
113 |
|
115 | |||
114 | * :file:`Release.py`. Move to ??? or remove? |
|
116 | * :file:`Release.py`. Move to ??? or remove? | |
115 |
|
117 | |||
116 | * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or |
|
118 | * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or | |
117 | :file:`IPython/frontend/shell.py`. |
|
119 | :file:`IPython/frontend/shell.py`. | |
118 |
|
120 | |||
119 | * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`. |
|
121 | * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`. | |
120 |
|
122 | |||
121 | * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`. |
|
123 | * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`. | |
122 |
|
124 | |||
123 | * :file:`completer.py`. Move to :file:`IPython/core/completer.py`. |
|
125 | * :file:`completer.py`. Move to :file:`IPython/core/completer.py`. | |
124 |
|
126 | |||
125 | * :file:`config`. Good where it is! |
|
127 | * :file:`config`. Good where it is! | |
126 |
|
128 | |||
127 | * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`. |
|
129 | * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`. | |
128 |
|
130 | |||
129 | * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`. |
|
131 | * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`. | |
130 |
|
132 | |||
131 | * :file:`dtutils.py`. Remove or move to :file:`IPython.testing` or |
|
133 | * :file:`dtutils.py`. Remove or move to :file:`IPython.testing` or | |
132 | :file:`IPython.lib`. |
|
134 | :file:`IPython.lib`. | |
133 |
|
135 | |||
134 | * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`. |
|
136 | * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`. | |
135 | Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`? |
|
137 | Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`? | |
136 |
|
138 | |||
137 | * :file:`external`. Good where it is! |
|
139 | * :file:`external`. Good where it is! | |
138 |
|
140 | |||
139 | * :file:`frontend`. Good where it is! |
|
141 | * :file:`frontend`. Good where it is! | |
140 |
|
142 | |||
141 | * :file:`generics.py`. Move to :file:`IPython.python`. |
|
143 | * :file:`generics.py`. Move to :file:`IPython.python`. | |
142 |
|
144 | |||
143 | * :file:`genutils.py`. Move to :file:`IPython.python` and break up into different |
|
145 | * :file:`genutils.py`. Move to :file:`IPython.python` and break up into different | |
144 | modules. |
|
146 | modules. | |
145 |
|
147 | |||
146 | * :file:`gui`. Eventually this should be moved to a subdir of |
|
148 | * :file:`gui`. Eventually this should be moved to a subdir of | |
147 | :file:`IPython.frontend`. |
|
149 | :file:`IPython.frontend`. | |
148 |
|
150 | |||
149 | * :file:`history.py`. Move to :file:`IPython.core`. |
|
151 | * :file:`history.py`. Move to :file:`IPython.core`. | |
150 |
|
152 | |||
151 | * :file:`hooks.py`. Move to :file:`IPython.core`. |
|
153 | * :file:`hooks.py`. Move to :file:`IPython.core`. | |
152 |
|
154 | |||
153 | * :file:`ipapi.py`. Move to :file:`IPython.core`. |
|
155 | * :file:`ipapi.py`. Move to :file:`IPython.core`. | |
154 |
|
156 | |||
155 | * :file:`iplib.py`. Move to :file:`IPython.core`. |
|
157 | * :file:`iplib.py`. Move to :file:`IPython.core`. | |
156 |
|
158 | |||
157 | * :file:`ipmaker.py`: Move to :file:`IPython.core`. |
|
159 | * :file:`ipmaker.py`: Move to :file:`IPython.core`. | |
158 |
|
160 | |||
159 | * :file:`ipstruct.py`. Move to :file:`IPython.python`. |
|
161 | * :file:`ipstruct.py`. Move to :file:`IPython.python`. | |
160 |
|
162 | |||
161 | * :file:`irunner.py`. Move to :file:`IPython.scripts`. |
|
163 | * :file:`irunner.py`. Move to :file:`IPython.scripts`. | |
162 |
|
164 | |||
163 | * :file:`kernel`. Good where it is. |
|
165 | * :file:`kernel`. Good where it is. | |
164 |
|
166 | |||
165 | * :file:`macro.py`. Move to :file:`IPython.core`. |
|
167 | * :file:`macro.py`. Move to :file:`IPython.core`. | |
166 |
|
168 | |||
167 | * :file:`numutils.py`. Move to :file:`IPython.sandbox`. |
|
169 | * :file:`numutils.py`. Move to :file:`IPython.sandbox`. | |
168 |
|
170 | |||
169 | * :file:`platutils.py`. Move to :file:`IPython.python`. |
|
171 | * :file:`platutils.py`. Move to :file:`IPython.python`. | |
170 |
|
172 | |||
171 | * :file:`platutils_dummy.py`. Move to :file:`IPython.python`. |
|
173 | * :file:`platutils_dummy.py`. Move to :file:`IPython.python`. | |
172 |
|
174 | |||
173 | * :file:`platutils_posix.py`. Move to :file:`IPython.python`. |
|
175 | * :file:`platutils_posix.py`. Move to :file:`IPython.python`. | |
174 |
|
176 | |||
175 | * :file:`platutils_win32.py`. Move to :file:`IPython.python`. |
|
177 | * :file:`platutils_win32.py`. Move to :file:`IPython.python`. | |
176 |
|
178 | |||
177 | * :file:`prefilter.py`: Move to :file:`IPython.core`. |
|
179 | * :file:`prefilter.py`: Move to :file:`IPython.core`. | |
178 |
|
180 | |||
179 | * :file:`rlineimpl.py`. Move to :file:`IPython.core`. |
|
181 | * :file:`rlineimpl.py`. Move to :file:`IPython.core`. | |
180 |
|
182 | |||
181 | * :file:`shadowns.py`. Move to :file:`IPython.core`. |
|
183 | * :file:`shadowns.py`. Move to :file:`IPython.core`. | |
182 |
|
184 | |||
183 | * :file:`shellglobals.py`. Move to :file:`IPython.core`. |
|
185 | * :file:`shellglobals.py`. Move to :file:`IPython.core`. | |
184 |
|
186 | |||
185 | * :file:`strdispatch.py`. Move to :file:`IPython.python`. |
|
187 | * :file:`strdispatch.py`. Move to :file:`IPython.python`. | |
186 |
|
188 | |||
187 | * :file:`testing`. Good where it is. |
|
189 | * :file:`testing`. Good where it is. | |
188 |
|
190 | |||
189 | * :file:`tests`. Good where it is. |
|
191 | * :file:`tests`. Good where it is. | |
190 |
|
192 | |||
191 | * :file:`tools`. Things in here need to be looked at and moved elsewhere like |
|
193 | * :file:`tools`. Things in here need to be looked at and moved elsewhere like | |
192 | :file:`IPython.python`. |
|
194 | :file:`IPython.python`. | |
193 |
|
195 | |||
194 | * :file:`twshell.py`. Move to :file:`IPython.sandbox`. |
|
196 | * :file:`twshell.py`. Move to :file:`IPython.sandbox`. | |
195 |
|
197 | |||
196 | * :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`. |
|
198 | * :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`. | |
197 |
|
199 | |||
198 | * :file:`upgrade_dir.py`. Move to :file:`IPython/python/upgradedir.py`. |
|
200 | * :file:`upgrade_dir.py`. Move to :file:`IPython/python/upgradedir.py`. | |
199 |
|
201 | |||
200 | * :file:`usage.py`. Move to :file:`IPython.core`. |
|
202 | * :file:`usage.py`. Move to :file:`IPython.core`. | |
201 |
|
203 | |||
202 | * :file:`wildcard.py`. Move to :file:`IPython.python` or :file:`IPython.core`. |
|
204 | * :file:`wildcard.py`. Move to :file:`IPython.python` or :file:`IPython.core`. | |
203 |
|
205 | |||
204 | * :file:`winconsole.py`. Move to :file:`IPython.lib`. |
|
206 | * :file:`winconsole.py`. Move to :file:`IPython.lib`. | |
205 |
|
207 | |||
206 | Other things |
|
208 | Other things | |
207 | ============ |
|
209 | ============ | |
208 |
|
210 | |||
209 | When these files are moved around, a number of other things will happen at the same time: |
|
211 | When these files are moved around, a number of other things will happen at the same time: | |
210 |
|
212 | |||
211 | 1. Test files will be created for each module in IPython. Minimally, all |
|
213 | 1. Test files will be created for each module in IPython. Minimally, all | |
212 | modules will be imported as a part of the test. This will serve as a |
|
214 | modules will be imported as a part of the test. This will serve as a | |
213 | test of the module reorganization. These tests will be put into new |
|
215 | test of the module reorganization. These tests will be put into new | |
214 | :file:`tests` subdirectories that each package will have. |
|
216 | :file:`tests` subdirectories that each package will have. | |
215 |
|
217 | |||
216 | 2. PyFlakes and other code checkers will be run to look for problems. |
|
218 | 2. PyFlakes and other code checkers will be run to look for problems. | |
217 |
|
219 | |||
218 | 3. Modules will be renamed to comply with PEP 8 naming conventions: all |
|
220 | 3. Modules will be renamed to comply with PEP 8 naming conventions: all | |
219 | lowercase and no special characters like ``-`` or ``_``. |
|
221 | lowercase and no special characters like ``-`` or ``_``. | |
220 |
|
222 | |||
221 | 4. Existing tests will be moved to the appropriate :file:`tests` |
|
223 | 4. Existing tests will be moved to the appropriate :file:`tests` | |
222 | subdirectories. |
|
224 | subdirectories. | |
223 |
|
225 | |||
224 |
|
226 | |||
225 |
|
227 | |||
226 |
|
228 |
General Comments 0
You need to be logged in to leave comments.
Login now