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