.. _extensions_overview:

==================
IPython extensions
==================

Configuration files are just the first level of customization that IPython
supports. The next level is that of extensions. An IPython extension is an
importable Python module that has a a few special function. By defining these
functions, users can customize IPython by accessing the actual runtime objects
of IPython.  Here is a sample extension::

    # myextension.py

    def load_ipython_extension(ipython):
        # The ``ipython`` argument is the currently active 
        # :class:`InteractiveShell` instance that can be used in any way.
        # This allows you do to things like register new magics, plugins or
        # aliases.

    def unload_ipython_extension(ipython):
        # If you want your extension to be unloadable, put that logic here.

This :func:`load_ipython_extension` function is called after your extension is
imported and the currently active :class:`InteractiveShell` instance is passed
as the only argument. You can do anything you want with IPython at that point.

The :func:`load_ipython_extension` will be called again is you load or reload
the extension again. It is up to the extension author to add code to manage
that.

Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, 
:meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and 
:meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).

You can put your extension modules anywhere you want, as long as they can be
imported by Python's standard import mechanism. However, to make it easy to
write extensions, you can also put your extensions in
``os.path.join(self.ipython_dir, 'extensions')``. This directory is added to
``sys.path`` automatically.

Using extensions
================

There are two ways you can tell IPython to use your extension:

1. Listing it in a configuration file.
2. Using the ``%load_ext`` magic function.

To load an extension called :file:`myextension.py` add the following logic
to your configuration file::

    c.InteractiveShellApp.extensions = [
        'myextension'
    ]

To load that same extension at runtime, use the ``%load_ext`` magic:

.. sourcecode:: ipython

    In [1]: %load_ext myextension

To summarize, in conjunction with configuration files and profiles, IPython
extensions give you complete and flexible control over your IPython
setup.

Extensions bundled with IPython
===============================

.. toctree::
   :maxdepth: 1

   autoreload
   parallelmagic
   storemagic
   sympyprinting