reorg.txt
263 lines
| 7.4 KiB
| text/plain
|
TextLexer
Brian Granger
|
r1798 | ============================= | ||
IPython module reorganization | ||||
============================= | ||||
Brian Granger
|
r1913 | 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. | ||||
Brian Granger
|
r1798 | |||
.. warning:: | ||||
This effort will possibly break third party packages that use IPython as | ||||
a library or hack on the IPython internals. | ||||
.. warning:: | ||||
This effort will result in the removal from IPython of certain modules | ||||
that are not used anymore, don't currently work, are unmaintained, etc. | ||||
Brian Granger
|
r1907 | |||
Brian Granger
|
r1798 | Current subpackges | ||
================== | ||||
IPython currently has the following sub-packages: | ||||
* :mod:`IPython.config` | ||||
* :mod:`IPython.Extensions` | ||||
* :mod:`IPython.external` | ||||
* :mod:`IPython.frontend` | ||||
* :mod:`IPython.gui` | ||||
* :mod:`IPython.kernel` | ||||
* :mod:`IPython.testing` | ||||
* :mod:`IPython.tests` | ||||
* :mod:`IPython.tools` | ||||
* :mod:`IPython.UserConfig` | ||||
New Subpackages to be created | ||||
============================= | ||||
We propose to create the following new sub-packages: | ||||
* :mod:`IPython.core`. This sub-package will contain the core of the IPython | ||||
interpreter, but none of its extended capabilities. | ||||
* :mod:`IPython.lib`. IPython has many extended capabilities that are not part | ||||
Brian Granger
|
r1907 | of the IPython core. These things will go here. Any better names than | ||
:mod:`IPython.lib`? | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2008 | * :mod:`IPython.utils`. This sub-package will contain anything that might | ||
Brian Granger
|
r1907 | eventually be found in the Python standard library, like things in | ||
Brian Granger
|
r2009 | :mod:`genutils`. Each sub-module in this sub-package should contain | ||
functions and classes that serve a single purpose. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2008 | * :mod:`IPython.deathrow`. This is for code that is untested and/or rotting | ||
and needs to be removed from IPython. Eventually all this code will either | ||||
i) be revived by someone willing to maintain it with tests and docs and | ||||
Brian Granger
|
r2006 | re-included into IPython or 2) be removed from IPython proper, but put into | ||
Brian Granger
|
r2008 | a separate top-level (not IPython) package that we keep around. No new code | ||
will be allowed here. | ||||
* :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's | ||||
standards, but that we plan on keeping. To be moved out of this sub-package | ||||
a module needs to have a maintainer, tests and documentation. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2010 | Prodecure | ||
========= | ||||
1. Move the file to its new location with its new name. | ||||
2. Rename all import statements to reflect the change. | ||||
3. Run PyFlakes on each changes module. | ||||
3. Add tests/test_imports.py to test it. | ||||
Need to modify iptests to properly skip modules that are no longer top | ||||
level modules. | ||||
Brian Granger
|
r2016 | Need to update the top level IPython/__init__.py file. | ||
Brian Granger
|
r1798 | Where things will be moved | ||
========================== | ||||
Brian Granger
|
r2053 | Top-level modules: | ||
Brian Granger
|
r2012 | * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`. | ||
Brian Granger
|
r2011 | * :file:`ColorANSI.py`. Move to :file:`IPython/utils/coloransi.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2012 | * :file:`completer.py`. Move to :file:`IPython/core/completer.py`. | ||
Brian Granger
|
r1907 | * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2016 | * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`. | ||
Brian Granger
|
r2017 | * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`. | ||
Brian Granger
|
r2016 | |||
Brian Granger
|
r2018 | * :file:`DPyGetOpt.py`. Move to :mod:`IPython.utils` and replace with newer options parser. | ||
Brian Granger
|
r2016 | |||
Brian Granger
|
r2020 | * :file:`dtutils.py`. Move to :file:`IPython.deathrow`. | ||
Brian Granger
|
r2019 | |||
Brian Granger
|
r2022 | * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`. | ||
Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`? | ||||
Brian Granger
|
r2020 | * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`. | ||
Brian Granger
|
r2019 | |||
Brian Granger
|
r2022 | * :file:`generics.py`. Move to :file:`IPython.python`. | ||
Brian Granger
|
r2019 | |||
Brian Granger
|
r2023 | * :file:`genutils.py`. Move to :file:`IPython.utils`. | ||
Brian Granger
|
r1907 | * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2025 | * :file:`numutils.py`. Move to :file:`IPython.sandbox`. | ||
* :file:`twshell.py`. Move to :file:`IPython.sandbox`. | ||||
* :file:`Extensions`. This needs to be gone through separately. Minimally, | ||||
the package should be renamed to :file:`extensions`. | ||||
* :file:`history.py`. Move to :file:`IPython.core`. | ||||
Brian Granger
|
r2026 | * :file:`hooks.py`. Move to :file:`IPython.core`. | ||
Brian Granger
|
r2028 | * :file:`ipapi.py`. Move to :file:`IPython.core`. | ||
Brian Granger
|
r2048 | * :file:`iplib.py`. Move to :file:`IPython.core`. | ||
* :file:`ipmaker.py`: Move to :file:`IPython.core`. | ||||
Brian Granger
|
r2028 | |||
Brian Granger
|
r2048 | * :file:`ipstruct.py`. Move to :file:`IPython.python`. | ||
* :file:`irunner.py`. Move to :file:`IPython.scripts`. ??? | ||||
Brian Granger
|
r2025 | |||
Brian Granger
|
r2048 | * :file:`Itpl.py`. Move to :file:`deathrow/Itpl.py`. Copy already in | ||
:file:`IPython.external`. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2048 | * :file:`macro.py`. Move to :file:`IPython.core`. | ||
Brian Granger
|
r1907 | * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2048 | * :file:`platutils.py`. Move to :file:`IPython.python`. | ||
* :file:`platutils_dummy.py`. Move to :file:`IPython.python`. | ||||
* :file:`platutils_posix.py`. Move to :file:`IPython.python`. | ||||
* :file:`platutils_win32.py`. Move to :file:`IPython.python`. | ||||
* :file:`prefilter.py`: Move to :file:`IPython.core`. | ||||
Brian Granger
|
r1907 | * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or | ||
:file:`IPython/frontend/prompts.py`. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1913 | * :file:`PyColorize.py`. Replace with pygments? If not, move to | ||
:file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or | ||||
:mod:`IPython.python`? | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`Release.py`. Move to ??? or remove? | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2048 | * :file:`rlineimpl.py`. Move to :file:`IPython.core`. | ||
* :file:`shadowns.py`. Move to :file:`IPython.core`. | ||||
Brian Granger
|
r1907 | * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or | ||
:file:`IPython/frontend/shell.py`. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2048 | * :file:`shellglobals.py`. Move to :file:`IPython.core`. | ||
* :file:`strdispatch.py`. Move to :file:`IPython.python`. | ||||
Brian Granger
|
r2053 | * :file:`twshell.py`. Move to :file:`IPython.sandbox`. | ||
* :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`. | ||||
* :file:`upgrade_dir.py`. Move to :file:`IPython/utils/upgradedir.py`. | ||||
* :file:`usage.py`. Move to :file:`IPython.core`. | ||||
* :file:`wildcard.py`. Move to :file:`IPython.utils`. | ||||
* :file:`winconsole.py`. Move to :file:`IPython.utils`. | ||||
Top-level sub-packages: | ||||
Brian Granger
|
r2048 | * :file:`testing`. Good where it is. | ||
* :file:`tests`. Good where it is. | ||||
* :file:`tools`. Things in here need to be looked at and moved elsewhere like | ||||
Brian Granger
|
r2053 | :file:`IPython.utils`. | ||
Brian Granger
|
r2048 | |||
Brian Granger
|
r1907 | * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`config`. Good where it is! | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`external`. Good where it is! | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`frontend`. Good where it is! | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`gui`. Eventually this should be moved to a subdir of | ||
:file:`IPython.frontend`. | ||||
Brian Granger
|
r1798 | |||
Brian Granger
|
r1907 | * :file:`kernel`. Good where it is. | ||
Brian Granger
|
r1798 | |||
Brian Granger
|
r2025 | |||
Brian Granger
|
r1798 | |||
Other things | ||||
============ | ||||
When these files are moved around, a number of other things will happen at the same time: | ||||
1. Test files will be created for each module in IPython. Minimally, all | ||||
modules will be imported as a part of the test. This will serve as a | ||||
test of the module reorganization. These tests will be put into new | ||||
:file:`tests` subdirectories that each package will have. | ||||
Brian Granger
|
r1907 | 2. PyFlakes and other code checkers will be run to look for problems. | ||
3. Modules will be renamed to comply with PEP 8 naming conventions: all | ||||
Brian Granger
|
r1798 | lowercase and no special characters like ``-`` or ``_``. | ||
Brian Granger
|
r1907 | 4. Existing tests will be moved to the appropriate :file:`tests` | ||
Brian Granger
|
r1798 | subdirectories. | ||