reorg.txt

.. _module_reorg:

===========================
IPython module organization
===========================

As of the 0.11 release of IPython, the top-level packages and modules have
been completely reorganized.  This section describes the purpose of the
top-level IPython subpackages.

Subpackage descriptions
=======================

* :mod:`IPython.config`.  This package contains the :ref:`configuration system
  <config_index>` of IPython, as well as default configuration files for the
  different IPython applications.

* :mod:`IPython.core`. This sub-package contains the core of the IPython
  interpreter, but none of its extended capabilities.

* :mod:`IPython.deathrow`. This is for code that is outdated, untested,
  rotting, or that belongs in a separate third party project. Eventually all
  this code will either 1) be revived by someone willing to maintain it with
  tests and docs and re-included into IPython or 2) be removed from IPython
  proper, but put into a separate third-party Python package. No new code will
  be allowed here. If your favorite extension has been moved here please
  contact the IPython developer mailing list to help us determine the best
  course of action.

* :mod:`IPython.extensions`.  This package contains fully supported IPython
  extensions.  These extensions adhere to the official IPython extension API
  and can be enabled by adding them to a field in the configuration file.
  If your extension is no longer in this location, please look in
  :mod:`IPython.quarantine` and :mod:`IPython.deathrow` and contact the
  IPython developer mailing list.

* :mod:`IPython.external`. This package contains third party packages and
  modules that IPython ships internally to reduce the number of dependencies.
  Usually, these are short, single file modules.

* :mod:`IPython.frontend`. This package contains the various IPython
  frontends which communicate with the :mod:`IPython.zmq` kernels (see
  :ref:`Messaging in IPython <messaging>`). This includes the
  :ref:`ipython notebook <htmlnotebook>`, :ref:`ipython qtconsole
  <qtconsole>`, and :ref:`ipython console <two_process_console>` entry points.

* :mod:`IPython.lib`. IPython has many extended capabilities that are not part
  of the IPython core. These things will go here and in.  Modules in this
  package are similar to extensions, but don't adhere to the official
  IPython extension API.

* :mod:`IPython.nbformat`.  This package contains code related to reading and
  writing :ref:`IPython Notebook's <htmlnotebook>` file format (`.ipynb`
  files).

* :mod:`IPython.parallel`.  This contains :ref:`IPython's parallel computing
  system <parallel_index>`. This previously lived under :mod:`IPython.kernel`,
  but that module has been deprecated.

* :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 approval of the core IPython developers, tests and
  documentation. If your favorite extension has been moved here please contact
  the IPython developer mailing list to help us determine the best course of
  action.

* :mod:`IPython.scripts`.  This package contains a variety of top-level
  command line scripts.  Eventually, these should be moved to the 
  :file:`scripts` subdirectory of the appropriate IPython subpackage.

* :mod:`IPython.testing`.  This package contains code related to the IPython
  test suite, which  locates and executes the `tests` submodules of all
  IPython sub-packages. It also contains decorators and utilities relevant for
  testing.

* :mod:`IPython.utils`. This sub-package will contain anything that might
  eventually be found in the Python standard library, like things in
  :mod:`genutils`. Each sub-module in this sub-package should contain
  functions and classes that serve a single purpose and that don't
  depend on things in the rest of IPython.

* :mod:`IPython.zmq`. This sub-package contains code related to starting and
  managing IPython kernels, which :mod:`IPython.frontend` instances can then
  communicate with (see :ref:`Messaging in IPython <messaging>`).