extensions.txt
61 lines
| 2.1 KiB
| text/plain
|
TextLexer
Brian Granger
|
r2749 | .. _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:: | ||||
MinRK
|
r4040 | c.InteractiveShellApp.extensions = [ | ||
Brian Granger
|
r2749 | 'myextension' | ||
] | ||||
Thomas Kluyver
|
r4198 | To load that same extension at runtime, use the ``%load_ext`` magic: | ||
Brian Granger
|
r2749 | |||
.. 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. | ||||