Add plugin infrastructure for wizard.app.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/TODO b/TODO
index 2420ca6b98358c2aafb23ec1ebf1c0ef06b35173..6750cb80d2643b78f583e1b23635dde43f636a5e 100644 (file)
--- a/TODO
+++ b/TODO
@@ -15,13 +15,6 @@ TODO NOW:
   scripts and start executing there?
 - Write the code to make Wordpress figure out its URL from the database
 
-- Plugin architecture
-     http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins
-     http://peak.telecommunity.com/DevCenter/PkgResources#entry-points
-     https://xvm.mit.edu:1111/trunk/packages/invirt-base/python/invirt/authz.py
-     https://xvm.mit.edu:1111/trunk/packages/xvm-authz-locker/setup.py
-     http://pylonshq.com/docs/en/0.9.7/advanced_pylons/entry_points_and_plugins/
-
 - Remerges aren't reflected in the parent files, so `git diff` output is
   spurious.  Not sure how to fix this w/o tree hackery.
 - Sometimes users remove files. Well, if those files change, they automatically

diff --git a/doc/index.rst b/doc/index.rst
index 912228ddb237845b3bcf93d3ea81b0d5f06736d8..7d88a5449ebe7fc19a0357001bf16870d5d94848 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -59,6 +59,7 @@ Table of Contents
     create
     upgrade
     testing
+    plugin
     glossary
 
 Modules

diff --git a/doc/plugin.rst b/doc/plugin.rst
new file mode 100644 (file)
index 0000000..2267bfa
--- /dev/null
+++ b/doc/plugin.rst
@@ -0,0 +1,29 @@
+Plugin architecture
+===================
+
+:Author: Edward Z. Yang <ezyang@mit.edu>
+
+Wizard uses the standard :mod:`pkg_resources` plugin infrastructure from
+`setuptools <http://pypi.python.org/pypi/setuptools>`_ to add support
+for plugins in Wizard.  We recommend the following excellent tutorials
+in for learning how to register plugins using this infrastructure:
+
+* `Using Entry Points to Write Plugins
+  <http://pylonshq.com/docs/en/0.9.7/advanced_pylons/entry_points_and_plugins/>`_
+* `Dynamic Discovery of Services and Plugins
+  <http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins>`_
+
+.. todo::
+
+    Describe how to register plugins without actually have to install
+    any eggs.
+
+Here is a bird's eye view of the various plugin systems in Wizard.
+
+:mod:`wizard.app`
+-----------------
+
+Use ``wizard.app`` to register custom applications that Wizard has
+support for.  Key is user-visible name of application (e.g.
+``wordpress``) and value is application class to be instantiated to
+represent this application (e.g. ``wizard.app.wordpress:Application``).

diff --git a/wizard/app/__init__.py b/wizard/app/__init__.py
index ae99e3e58dfa34aebe3916c4f370f186a2bcfe00..1c8b477e997027abeabc5dd2944b32efca648d7b 100644 (file)
--- a/wizard/app/__init__.py
+++ b/wizard/app/__init__.py
@@ -6,6 +6,18 @@ You'll need to know how to overload the :class:`Application` class
 and use some of the functions in this module in order to specify
 new applications.
 
+To specify custom applications as plugins,  add the following ``entry_points``
+configuration::
+
+    [wizard.app]
+    yourappname = your.module:Application
+    otherappname = your.other.module:Application
+
+.. note::
+
+    Wizard will complain loudly if ``yourappname`` conflicts with an
+    application name defined by someone else.
+
 There are some submodules for programming languages that define common
 functions and data that may be used by applications in that language.  See:
 
@@ -32,23 +44,48 @@ import random
 import string
 import urlparse
 import tempfile
+import pkg_resources
 
 import wizard
 from wizard import resolve, scripts, shell, util
 
-_application_list = [
+# SCRIPTS SPECIFIC
+_scripts_application_list = [
     "mediawiki", "wordpress", "joomla", "e107", "gallery2",
     "phpBB", "advancedbook", "phpical", "trac", "turbogears", "django",
     # these are technically deprecated
     "advancedpoll", "gallery",
 ]
-_applications = None
+def _scripts_make(name):
+    """Makes an application, but uses the correct subtype if available."""
+    try:
+        __import__("wizard.app." + name)
+        return getattr(wizard.app, name).Application(name)
+    except ImportError as error:
+        # XXX ugly hack to check if the import error is from the top level
+        # module we care about or a submodule. should be an archetectural change.
+        if error.args[0].split()[-1]==name:
+            return Application(name)
+        else:
+            raise
 
+_applications = None
 def applications():
     """Hash table for looking up string application name to instance"""
     global _applications
     if not _applications:
-        _applications = dict([(n,Application.make(n)) for n in _application_list ])
+        # SCRIPTS SPECIFIC
+        _applications = dict([(n,_scripts_make(n)) for n in _scripts_application_list ])
+        # setup plugins
+        for dist in pkg_resources.working_set:
+            for appname, appclass in dist.get_entry_map("wizard.app").items():
+                if appname in _applications:
+                    newname = dist.key + ":" + appname
+                    if newname in _applications:
+                        raise Exception("Unrecoverable application name conflict for %s from %s", appname, dist.key)
+                    logging.warning("Could not overwrite %s, used %s instead", appname, newname)
+                    appname = newname
+                _applications[appname] = appclass(appname)
     return _applications
 
 def getApplication(appname):
@@ -256,6 +293,8 @@ class Application(object):
                 shell.call("git", "rm", file)
                 continue
             # manual resolutions
+            # XXX: this functionality is mostly subsumed by the rerere
+            # tricks we do
             if file in self.resolutions:
                 contents = open(file, "r").read()
                 for spec, result in self.resolutions[file]:
@@ -418,19 +457,6 @@ class Application(object):
         be displayed in verbose mode.
         """
         return filename in self.parametrized_files
-    @staticmethod
-    def make(name):
-        """Makes an application, but uses the correct subtype if available."""
-        try:
-            __import__("wizard.app." + name)
-            return getattr(wizard.app, name).Application(name)
-        except ImportError as error:
-            # XXX ugly hack to check if the import error is from the top level
-            # module we care about or a submodule. should be an archetectural change.
-            if error.args[0].split()[-1]==name:
-                return Application(name)
-            else:
-                raise
 
 class ApplicationVersion(object):
     """Represents an abstract notion of a version for an application, where