docs/source/config/extensions/index.txt

.. _extensions_overview:

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

A level above configuration are IPython extensions, Python modules which modify
the behaviour of the shell. They are referred to by an importable module name,
and can be placed anywhere you'd normally import from, or in
``$IPYTHONDIR/extensions/``.

Getting extensions
==================

A few important extensions are :ref:`bundled with IPython <bundled_extensions>`.
Others can be found on the `extensions index
<http://wiki.ipython.org/Extensions_Index>`_ on the wiki, and installed with
the ``%install_ext`` magic function.

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

To load an extension while IPython is running, use the ``%load_ext`` magic:

.. sourcecode:: ipython

    In [1]: %load_ext myextension

To load it each time IPython starts, list it in your configuration file::

    c.InteractiveShellApp.extensions = [
        'myextension'
    ]

Writing extensions
==================

An IPython extension is an importable Python module that has a couple of special
functions to load and unload it. Here is a template::

    # myextension.py

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

    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:`~IPython.core.interactiveshell.InteractiveShell`
instance is passed as the only argument. You can do anything you want with
IPython at that point.

:func:`load_ipython_extension` will be called again if 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(ip.ipython_dir, 'extensions')``. This directory is added to
``sys.path`` automatically.

When your extension is ready for general use, please add it to the `extensions
index <http://wiki.ipython.org/Extensions_Index>`_.

Plugin class
------------

More advanced extensions might want to subclass :class:`IPython.core.plugin.Plugin`.
A plugin can have options configured by IPython's main :ref:`configuration
system <config_overview>`. The code to load and unload it looks like this::

    def load_ipython_extension(ip):
        """Load the plugin in IPython."""
        plugin = MyPlugin(shell=ip, config=ip.config)
        try:
            ip.plugin_manager.register_plugin('myplugin', plugin)
        except KeyError:
            print("Already loaded")
    
    def unload_ipython_extension(ip):
        ip.plugin_manager.unregister_plugin('myplugin')

For examples, see these files:

* :file:`IPython/extensions/autoreload.py`
* :file:`IPython/extensions/storemagic.py`

.. _bundled_extensions:

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

.. toctree::
   :maxdepth: 1

   autoreload
   cythonmagic
   octavemagic
   rmagic
   storemagic
   sympyprinting