mediagoblin/tools/pluginapi.py

   1 # GNU MediaGoblin -- federated, autonomous media hosting
   2 # Copyright (C) 2011, 2012 MediaGoblin contributors.  See AUTHORS.
   3 #
   4 # This program is free software: you can redistribute it and/or modify
   5 # it under the terms of the GNU Affero General Public License as published by
   6 # the Free Software Foundation, either version 3 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU Affero General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU Affero General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 """
  18 This module implements the plugin api bits.
  19
  20 Two things about things in this module:
  21
  22 1. they should be excessively well documented because we should pull
  23    from this file for the docs
  24
  25 2. they should be well tested
  26
  27
  28 How do plugins work?
  29 ====================
  30
  31 Plugins are structured like any Python project. You create a Python package.
  32 In that package, you define a high-level ``__init__.py`` module that has a
  33 ``hooks`` dict that maps hooks to callables that implement those hooks.
  34
  35 Additionally, you want a LICENSE file that specifies the license and a
  36 ``setup.py`` that specifies the metadata for packaging your plugin. A rough
  37 file structure could look like this::
  38
  39     myplugin/
  40      |- setup.py         # plugin project packaging metadata
  41      |- README           # holds plugin project information
  42      |- LICENSE          # holds license information
  43      |- myplugin/        # plugin package directory
  44         |- __init__.py   # has hooks dict and code
  45
  46
  47 Lifecycle
  48 =========
  49
  50 1. All the modules listed as subsections of the ``plugins`` section in
  51    the config file are imported. MediaGoblin registers any hooks in
  52    the ``hooks`` dict of those modules.
  53
  54 2. After all plugin modules are imported, the ``setup`` hook is called
  55    allowing plugins to do any set up they need to do.
  56
  57 """
  58
  59 import logging
  60
  61 from functools import wraps
  62
  63 from mediagoblin import mg_globals
  64
  65
  66 _log = logging.getLogger(__name__)
  67
  68
  69 class PluginManager(object):
  70     """Manager for plugin things
  71
  72     .. Note::
  73
  74        This is a Borg class--there is one and only one of this class.
  75     """
  76     __state = {
  77         # list of plugin classes
  78         "plugins": [],
  79
  80         # map of hook names -> list of callables for that hook
  81         "hooks": {},
  82
  83         # list of registered template paths
  84         "template_paths": set(),
  85
  86         # list of template hooks
  87         "template_hooks": {},
  88
  89         # list of registered routes
  90         "routes": [],
  91         }
  92
  93     def clear(self):
  94         """This is only useful for testing."""
  95         # Why lists don't have a clear is not clear.
  96         del self.plugins[:]
  97         del self.routes[:]
  98         self.hooks.clear()
  99         self.template_paths.clear()
 100
 101     def __init__(self):
 102         self.__dict__ = self.__state
 103
 104     def register_plugin(self, plugin):
 105         """Registers a plugin class"""
 106         self.plugins.append(plugin)
 107
 108     def register_hooks(self, hook_mapping):
 109         """Takes a hook_mapping and registers all the hooks"""
 110         for hook, callables in hook_mapping.items():
 111             if isinstance(callables, (list, tuple)):
 112                 self.hooks.setdefault(hook, []).extend(list(callables))
 113             else:
 114                 # In this case, it's actually a single callable---not a
 115                 # list of callables.
 116                 self.hooks.setdefault(hook, []).append(callables)
 117
 118     def get_hook_callables(self, hook_name):
 119         return self.hooks.get(hook_name, [])
 120
 121     def register_template_path(self, path):
 122         """Registers a template path"""
 123         self.template_paths.add(path)
 124
 125     def get_template_paths(self):
 126         """Returns a tuple of registered template paths"""
 127         return tuple(self.template_paths)
 128
 129     def register_route(self, route):
 130         """Registers a single route"""
 131         _log.debug('registering route: {0}'.format(route))
 132         self.routes.append(route)
 133
 134     def get_routes(self):
 135         return tuple(self.routes)
 136
 137     def register_template_hooks(self, template_hooks):
 138         for hook, templates in template_hooks.items():
 139             if isinstance(templates, (list, tuple)):
 140                 self.template_hooks.setdefault(hook, []).extend(list(templates))
 141             else:
 142                 # In this case, it's actually a single callable---not a
 143                 # list of callables.
 144                 self.template_hooks.setdefault(hook, []).append(templates)
 145
 146     def get_template_hooks(self, hook_name):
 147         return self.template_hooks.get(hook_name, [])
 148
 149
 150 def register_routes(routes):
 151     """Registers one or more routes
 152
 153     If your plugin handles requests, then you need to call this with
 154     the routes your plugin handles.
 155
 156     A "route" is a `routes.Route` object. See `the routes.Route
 157     documentation
 158     <http://routes.readthedocs.org/en/latest/modules/route.html>`_ for
 159     more details.
 160
 161     Example passing in a single route:
 162
 163     >>> register_routes(('about-view', '/about',
 164     ...     'mediagoblin.views:about_view_handler'))
 165
 166     Example passing in a list of routes:
 167
 168     >>> register_routes([
 169     ...     ('contact-view', '/contact', 'mediagoblin.views:contact_handler'),
 170     ...     ('about-view', '/about', 'mediagoblin.views:about_handler')
 171     ... ])
 172
 173
 174     .. Note::
 175
 176        Be careful when designing your route urls. If they clash with
 177        core urls, then it could result in DISASTER!
 178     """
 179     if isinstance(routes, list):
 180         for route in routes:
 181             PluginManager().register_route(route)
 182     else:
 183         PluginManager().register_route(routes)
 184
 185
 186 def register_template_path(path):
 187     """Registers a path for template loading
 188
 189     If your plugin has templates, then you need to call this with
 190     the absolute path of the root of templates directory.
 191
 192     Example:
 193
 194     >>> my_plugin_dir = os.path.dirname(__file__)
 195     >>> template_dir = os.path.join(my_plugin_dir, 'templates')
 196     >>> register_template_path(template_dir)
 197
 198     .. Note::
 199
 200        You can only do this in `setup_plugins()`. Doing this after
 201        that will have no effect on template loading.
 202
 203     """
 204     PluginManager().register_template_path(path)
 205
 206
 207 def get_config(key):
 208     """Retrieves the configuration for a specified plugin by key
 209
 210     Example:
 211
 212     >>> get_config('mediagoblin.plugins.sampleplugin')
 213     {'foo': 'bar'}
 214     >>> get_config('myplugin')
 215     {}
 216     >>> get_config('flatpages')
 217     {'directory': '/srv/mediagoblin/pages', 'nesting': 1}}
 218
 219     """
 220
 221     global_config = mg_globals.global_config
 222     plugin_section = global_config.get('plugins', {})
 223     return plugin_section.get(key, {})
 224
 225
 226 def register_template_hooks(template_hooks):
 227     """
 228     Register a dict of template hooks.
 229
 230     Takes template_hooks as an argument, which is a dictionary of
 231     template hook names/keys to the templates they should provide.
 232     (The value can either be a single template path or an iterable
 233     of paths.)
 234
 235     Example:
 236       {"media_sidebar": "/plugin/sidemess/mess_up_the_side.html",
 237        "media_descriptionbox": ["/plugin/sidemess/even_more_mess.html",
 238                                 "/plugin/sidemess/so_much_mess.html"]}
 239     """
 240     PluginManager().register_template_hooks(template_hooks)
 241
 242
 243 def get_hook_templates(hook_name):
 244     """
 245     Get a list of hook templates for this hook_name.
 246
 247     Note: for the most part, you access this via a template tag, not
 248     this method directly, like so:
 249
 250       {% template_hook "media_sidebar" %}
 251
 252     ... which will include all templates for you, partly using this
 253     method.
 254
 255     Returns:
 256       A list of strings representing template paths.
 257
 258     """
 259     return PluginManager().get_template_hooks(hook_name)