Source code for girder.plugin

This module defines functions for registering, loading, and querying girder plugins.

import distutils.dist
from functools import wraps
import io
import json
import os
from pkg_resources import iter_entry_points, resource_filename

from girder import logprint
from girder.exceptions import GirderException

_NAMESPACE = 'girder.plugin'
_pluginRegistry = None
_pluginLoadOrder = []
_pluginWebroots = {}

def getPluginWebroots():
    global _pluginWebroots
    return _pluginWebroots

[docs]def registerPluginWebroot(webroot, name): """ Adds a webroot to the global registry for plugins based on the plugin name. """ global _pluginWebroots _pluginWebroots[name] = webroot
class _PluginMeta(type): """ This is a metaclass applied to the ``GirderPlugin`` descriptor class. It exists to automatically wrap subclass load methods. """ def __new__(cls, classname, bases, classdict): if 'load' in classdict: classdict['load'] = _PluginMeta._wrapPluginLoad(classdict['load']) return type.__new__(cls, classname, bases, classdict) @staticmethod def _wrapPluginLoad(func): """Wrap a plugin load method to provide logging and ensure it is loaded only once.""" @wraps(func) def wrapper(self, *args, **kwargs): if not getattr(self, '_loaded', False): # This block is executed on the first call to the function. # The return value of the call is saved an attribute on the wrapper # for future invocations. self._return = func(self, *args, **kwargs) self._loaded = True _pluginLoadOrder.append( logprint.success('Loaded plugin "%s"' % return self._return return wrapper
[docs]class GirderPlugin(metaclass=_PluginMeta): """ This is a base class for describing a girder plugin. A plugin is registered by adding an entrypoint under the namespace ``girder.plugin``. This entrypoint should return a class derived from this class. Example :: class Cats(GirderPlugin): def load(self, info): # load dependent plugins girder.plugin.getPlugin('pets').load(info) import rest # register new rest endpoints, etc. """ #: This is the named displayed to users on the plugin page. Unlike the entrypoint name #: used internally, this name can be an arbitrary string. DISPLAY_NAME = None #: The path of the plugin's web client source code. This path is given relative to the python #: package. This property is used to link the web client source into the staging area while #: building in development mode. When this value is `None` it indicates there is no web client #: component. CLIENT_SOURCE_PATH = None def __init__(self, entrypoint): self._name = self._loaded = False self._dist = entrypoint.dist self._metadata = _readPackageMetadata(self._dist)
[docs] def npmPackages(self): """Return a dictionary of npm packages -> versions for building the plugin client. By default, this dictionary will be assembled from the CLIENT_SOURCE_PATH property by inspecting the package.json file in the indicated directory. Plugins can override this method customize the behaivor for advanced usage. """ if self.CLIENT_SOURCE_PATH is None: return {} packageJsonFile = resource_filename( self.__module__, os.path.join(self.CLIENT_SOURCE_PATH, 'package.json') ) if not os.path.isfile(packageJsonFile): raise Exception('Invalid web client path provided: %s' % packageJsonFile) with open(packageJsonFile, 'r') as f: packageJson = json.load(f) packageName = packageJson['name'] return {packageName: 'file:%s' % os.path.dirname(packageJsonFile)}
@property def name(self): """Return the plugin name defaulting to the entrypoint name.""" return self._name @property def displayName(self): """Return a user-friendly plugin name (defaults to the entrypoint name).""" return self.DISPLAY_NAME or self._name @property def description(self): """Return the plugin description defaulting to the classes docstring.""" return self._metadata.description @property def url(self): """Return a url reference to the plugin (usually a readthedocs page).""" return self._metadata.url @property def version(self): """Return the version of the plugin automatically determined from""" return self._metadata.version @property def loaded(self): """Return true if this plugin has been loaded.""" return getattr(self, '_loaded', False) def load(self, info): raise NotImplementedError('Plugins must define a load method')
def _readPackageMetadata(distribution): """Get a metadata object associated with a python package.""" metadata_string = distribution.get_metadata(distribution.PKG_INFO) metadata = distutils.dist.DistributionMetadata() metadata.read_pkg_file(io.StringIO(metadata_string)) return metadata def _getPluginRegistry(): """Return a dictionary containing all detected plugins. This function will discover plugins registered via entrypoints and return a mapping of plugin name -> plugin definition. The result is memoized because iteration through entrypoints is a slow operation. """ global _pluginRegistry if _pluginRegistry is not None: return _pluginRegistry _pluginRegistry = {} for entryPoint in iter_entry_points(_NAMESPACE): pluginClass = entryPoint.load() plugin = pluginClass(entryPoint) _pluginRegistry[] = plugin return _pluginRegistry
[docs]def getPlugin(name): """Return a plugin configuration object or None if the plugin is not found.""" registry = _getPluginRegistry() return registry.get(name)
def _loadPlugins(info, names=None): """Load plugins with the given app info object. If `names` is None, all installed plugins will be loaded. If `names` is a list, then only those plugins in the provided list will be loaded. """ if names is None: names = allPlugins() for name in names: pluginObject = getPlugin(name) if pluginObject is None: raise GirderException('Plugin %s is not installed' % name) pluginObject.load(info)
[docs]def allPlugins(): """Return a list of all detected plugins.""" return list(_getPluginRegistry().keys())
[docs]def loadedPlugins(): """Return a list of successfully loaded plugins.""" return _pluginLoadOrder[:]