doc/plugin.rst

   1 Plugin architecture
   2 ===================
   3
   4 :Author: Edward Z. Yang <ezyang@mit.edu>
   5
   6 Wizard uses the standard :mod:`pkg_resources` plugin infrastructure from
   7 `setuptools <http://pypi.python.org/pypi/setuptools>`_ to add support
   8 for plugins in Wizard.  We recommend the following excellent tutorials
   9 in for learning how to register plugins using this infrastructure:
  10
  11 * `Using Entry Points to Write Plugins
  12   <http://pylonshq.com/docs/en/0.9.7/advanced_pylons/entry_points_and_plugins/>`_
  13 * `Dynamic Discovery of Services and Plugins
  14   <http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins>`_
  15
  16 Wizard will automatically use any plugins that it sees registered, so
  17 plugin authors should take care to "do no harm" if a plugin is unable to
  18 do anything useful.
  19
  20
  21
  22 Registering plugins without eggs
  23 --------------------------------
  24
  25 To register a plugin without an egg, you need to prepare a special
  26 directory that you will add to your :envvar:`PYTHONPATH`.  Create a
  27 setuptools (not distutils) ``setup.py`` file that sets ``entry_points``
  28 to be the plugins that are to be registered, and then run ``python
  29 setup.py egg_info``.
  30
  31
  32
  33 ``wizard.app``
  34 --------------
  35
  36 Used to register custom applications that Wizard has
  37 support for.  Key is user-visible name of application (e.g.
  38 ``wordpress``) and value is application class (a subclass of
  39 :class:`wizard.app.Application`) to be instantiated to
  40 represent this application (e.g. ``wizard.app.wordpress:Application``)::
  41
  42     [wizard.app]
  43     wordpress = wizard.app.wordpress:Application
  44
  45 For more information on how to create an application, check
  46 :doc:`Creating a Repository <create>`.
  47
  48
  49
  50 .. _wizard.install.strategy:
  51
  52 ``wizard.install.strategy``
  53 -------------------
  54
  55 Used during installation to automatically determine values for
  56 installation parameters the user may have omitted.  Plugin should be a
  57 subclass of :class:`wizard.install.Strategy`.  The class that runs this
  58 plugin is :class:`wizard.install.ArgSchema`.
  59
  60
  61
  62 .. _wizard.sql.auth:
  63
  64 ``wizard.sql.auth``
  65 --------------------
  66
  67 Used to fill in a user's database authentication credentials if none are
  68 able to be determined from an application's configuration files.  Plugin
  69 should be a function that takes a single required argument ``url``,
  70 which is a :class:`sqlalchemy.engine.url.URL` with partial
  71 authentication information, including a database name, and should return either
  72 ``None`` if it was unable to fill in authentication credentials for the
  73 user, or the completed URL.  Mutating the passed argument and then
  74 returning it is the expected modus operandi of a plugin.  The function
  75 that runs this plugin is :func:`wizard.sql.auth`.
  76
  77 .. note::
  78
  79     If Wizard is able to determine the login credentials from the
  80     application's source files, these plugins will not be run.
  81
  82
  83
  84 .. _wizard.deploy.web:
  85
  86 ``wizard.deploy.web``
  87 ---------------------
  88
  89 Used to fill in a user's web URL if it is not able to be determined from
  90 an application's configuration files.  Plugin should be a function that
  91 takes a single required argument ``dir``, which is the directory to
  92 determint the web URL(s) for, and return a list or generator of
  93 :class:`urlparse.ParseResult` objects or URL strings of possible web locations
  94 for an application.  The function that runs this plugin is
  95 :func:`wizard.deploy.web`.
  96
  97 .. note::
  98
  99     If Wizard is able to determine the web URL from the application's
 100     source files or database, these plugins will not run.
 101
 102
 103
 104 .. _wizard.user.email:
 105
 106 ``wizard.user.email``
 107 ---------------------
 108
 109 Used to determine a user's email address.  By default, we use a
 110 heuristic approach;  if your system offers this information in a
 111 canonical form we recommend taking advantage of it.  Plugin should be a
 112 function that takes a single required argument ``name`` and returns a
 113 string email address corresponding to that user, or ``None`` if it
 114 was unable to determine an email address.  The function that runs this
 115 plugin is :func:`wizard.user.email`.
 116
 117 .. note::
 118
 119     If the :envvar:`EMAIL` environment variable is set and we are
 120     requesting the current user's email, these plugins will not run.
 121
 122
 123
 124 .. _wizard.user.operator:
 125
 126 ``wizard.user.operator``
 127 ------------------------
 128
 129 If Wizard is running as root or as a superuser masquerading as another
 130 user, it is still useful to record who was in front of the screen.  The default
 131 fallback is checking :envvar:`SUDO_USER`; if your system gives more
 132 information we recommend taking advantage of it.
 133
 134
 135
 136 .. _wizard.user.passwd:
 137
 138 ``wizard.user.passwd``
 139 ----------------------
 140
 141 If Wizard is running on a system with a network filesystem (such as NFS
 142 or AFS), the standard system ``passwd`` database may not actually
 143 resolve the username from a UID.  Use this hook to implement an
 144 alternative ``passwd`` lookup.  Plugin should be a function that takes a
 145 directory (to determine filesystem off of) and a user ID (to perform the
 146 lookup on).  The directory is guaranteed to be a real path.  The plugin
 147 should return an instance of :class:`wizard.user.Info` or ``None``, if
 148 it was unable to perform the lookup.  The function that runs this plugin
 149 is :func:`wizard.user.passwd`.
 150
 151
 152
 153 .. _wizard.user.quota:
 154
 155 ``wizard.user.quota``
 156 ---------------------
 157
 158 Wizard has safeguards for avoiding exceeding user quotas when an
 159 automated upgrade is being performed.  Unfortunately, methods for
 160 enforcing quotas are frequently highly system dependent.  Use this hook
 161 to implement quota usage and limit reporting.  Plugin should be a
 162 function that takes a single required argument ``dir``, which is the
 163 directory to determine the quota for, and return a tuple ``(quota usage,
 164 quota limit)`` or ``None`` if it could not determine quota.  The
 165 function that runs this plugin is :func:`wizard.user.quota`.