| | |
| | """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 |
| |
|
