|
|
.. _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.
|
|
|
|
|
|
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.Global.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.
|
|
|
|
