|
|
|
|
|
"""A class for managing IPython extensions.""" |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
import os |
|
|
import os.path |
|
|
import sys |
|
|
from importlib import import_module, reload |
|
|
|
|
|
from traitlets.config.configurable import Configurable |
|
|
from IPython.utils.path import ensure_dir_exists, compress_user |
|
|
from IPython.utils.decorators import undoc |
|
|
from traitlets import Instance |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
BUILTINS_EXTS = {"storemagic": False, "autoreload": False} |
|
|
|
|
|
|
|
|
class ExtensionManager(Configurable): |
|
|
"""A class to manage IPython extensions. |
|
|
|
|
|
An IPython extension is an importable Python module that has |
|
|
a function with the signature:: |
|
|
|
|
|
def load_ipython_extension(ipython): |
|
|
# Do things with ipython |
|
|
|
|
|
This 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, including defining new magic and aliases, adding new |
|
|
components, etc. |
|
|
|
|
|
You can also optionally define an :func:`unload_ipython_extension(ipython)` |
|
|
function, which will be called if the user unloads or reloads the extension. |
|
|
The extension manager will only call :func:`load_ipython_extension` again |
|
|
if the extension is reloaded. |
|
|
|
|
|
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. |
|
|
""" |
|
|
|
|
|
shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True) |
|
|
|
|
|
def __init__(self, shell=None, **kwargs): |
|
|
super(ExtensionManager, self).__init__(shell=shell, **kwargs) |
|
|
self.shell.observe( |
|
|
self._on_ipython_dir_changed, names=('ipython_dir',) |
|
|
) |
|
|
self.loaded = set() |
|
|
|
|
|
@property |
|
|
def ipython_extension_dir(self): |
|
|
return os.path.join(self.shell.ipython_dir, u'extensions') |
|
|
|
|
|
def _on_ipython_dir_changed(self, change): |
|
|
ensure_dir_exists(self.ipython_extension_dir) |
|
|
|
|
|
def load_extension(self, module_str: str): |
|
|
"""Load an IPython extension by its module name. |
|
|
|
|
|
Returns the string "already loaded" if the extension is already loaded, |
|
|
"no load function" if the module doesn't have a load_ipython_extension |
|
|
function, or None if it succeeded. |
|
|
""" |
|
|
try: |
|
|
return self._load_extension(module_str) |
|
|
except ModuleNotFoundError: |
|
|
if module_str in BUILTINS_EXTS: |
|
|
BUILTINS_EXTS[module_str] = True |
|
|
return self._load_extension("IPython.extensions." + module_str) |
|
|
raise |
|
|
|
|
|
def _load_extension(self, module_str: str): |
|
|
if module_str in self.loaded: |
|
|
return "already loaded" |
|
|
|
|
|
from IPython.utils.syspathcontext import prepended_to_syspath |
|
|
|
|
|
with self.shell.builtin_trap: |
|
|
if module_str not in sys.modules: |
|
|
mod = import_module(module_str) |
|
|
mod = sys.modules[module_str] |
|
|
if self._call_load_ipython_extension(mod): |
|
|
self.loaded.add(module_str) |
|
|
else: |
|
|
return "no load function" |
|
|
|
|
|
def unload_extension(self, module_str: str): |
|
|
"""Unload an IPython extension by its module name. |
|
|
|
|
|
This function looks up the extension's name in ``sys.modules`` and |
|
|
simply calls ``mod.unload_ipython_extension(self)``. |
|
|
|
|
|
Returns the string "no unload function" if the extension doesn't define |
|
|
a function to unload itself, "not loaded" if the extension isn't loaded, |
|
|
otherwise None. |
|
|
""" |
|
|
if BUILTINS_EXTS.get(module_str, False) is True: |
|
|
module_str = "IPython.extensions." + module_str |
|
|
if module_str not in self.loaded: |
|
|
return "not loaded" |
|
|
|
|
|
if module_str in sys.modules: |
|
|
mod = sys.modules[module_str] |
|
|
if self._call_unload_ipython_extension(mod): |
|
|
self.loaded.discard(module_str) |
|
|
else: |
|
|
return "no unload function" |
|
|
|
|
|
def reload_extension(self, module_str: str): |
|
|
"""Reload an IPython extension by calling reload. |
|
|
|
|
|
If the module has not been loaded before, |
|
|
:meth:`InteractiveShell.load_extension` is called. Otherwise |
|
|
:func:`reload` is called and then the :func:`load_ipython_extension` |
|
|
function of the module, if it exists is called. |
|
|
""" |
|
|
from IPython.utils.syspathcontext import prepended_to_syspath |
|
|
|
|
|
if BUILTINS_EXTS.get(module_str, False) is True: |
|
|
module_str = "IPython.extensions." + module_str |
|
|
|
|
|
if (module_str in self.loaded) and (module_str in sys.modules): |
|
|
self.unload_extension(module_str) |
|
|
mod = sys.modules[module_str] |
|
|
with prepended_to_syspath(self.ipython_extension_dir): |
|
|
reload(mod) |
|
|
if self._call_load_ipython_extension(mod): |
|
|
self.loaded.add(module_str) |
|
|
else: |
|
|
self.load_extension(module_str) |
|
|
|
|
|
def _call_load_ipython_extension(self, mod): |
|
|
if hasattr(mod, 'load_ipython_extension'): |
|
|
mod.load_ipython_extension(self.shell) |
|
|
return True |
|
|
|
|
|
def _call_unload_ipython_extension(self, mod): |
|
|
if hasattr(mod, 'unload_ipython_extension'): |
|
|
mod.unload_ipython_extension(self.shell) |
|
|
return True |
|
|
|
