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 .. _wizard.sql.drop:
  83
  84 ``wizard.sql.drop``
  85 ------------------------------
  86
  87 Used to remove a SQL database, as might be done when an application is
  88 being uninstalled.  Plugin should be a function that takes a single
  89 required argument ``dsn``, which is a
  90 :class:`sqlalchemy.engine.url.URL` and should return either ``None`` if
  91 it was unable to delete the database, or ``True`` in the event of
  92 success.  This is a good plugin to implement if you don't give your
  93 users ``DROP DATABASE`` permissions, and instead they have to create and
  94 delete databases through another interface.  The function that runs this
  95 plugin is :func:`wizard.sql.drop`.
  96
  97 .. _wizard.deploy.web:
  98
  99 ``wizard.deploy.web``
 100 ---------------------
 101
 102 Used to fill in a user's web URL if it is not able to be determined from
 103 an application's configuration files.  Plugin should be a function that
 104 takes a single required argument ``dir``, which is the directory to
 105 determint the web URL(s) for, and return a list or generator of
 106 :class:`urlparse.ParseResult` objects or URL strings of possible web locations
 107 for an application.  The function that runs this plugin is
 108 :func:`wizard.deploy.web`.
 109
 110 .. note::
 111
 112     If Wizard is able to determine the web URL from the application's
 113     source files or database, these plugins will not run.
 114
 115
 116
 117 .. _wizard.user.email:
 118
 119 ``wizard.user.email``
 120 ---------------------
 121
 122 Used to determine a user's email address.  By default, we use a
 123 heuristic approach;  if your system offers this information in a
 124 canonical form we recommend taking advantage of it.  Plugin should be a
 125 function that takes a single required argument ``name`` and returns a
 126 string email address corresponding to that user, or ``None`` if it
 127 was unable to determine an email address.  The function that runs this
 128 plugin is :func:`wizard.user.email`.
 129
 130 .. note::
 131
 132     If the :envvar:`EMAIL` environment variable is set and we are
 133     requesting the current user's email, these plugins will not run.
 134
 135
 136
 137 .. _wizard.user.operator:
 138
 139 ``wizard.user.operator``
 140 ------------------------
 141
 142 If Wizard is running as root or as a superuser masquerading as another
 143 user, it is still useful to record who was in front of the screen.  The default
 144 fallback is checking :envvar:`SUDO_USER`; if your system gives more
 145 information we recommend taking advantage of it.
 146
 147
 148
 149 .. _wizard.user.passwd:
 150
 151 ``wizard.user.passwd``
 152 ----------------------
 153
 154 If Wizard is running on a system with a network filesystem (such as NFS
 155 or AFS), the standard system ``passwd`` database may not actually
 156 resolve the username from a UID.  Use this hook to implement an
 157 alternative ``passwd`` lookup.  Plugin should be a function that takes a
 158 directory (to determine filesystem off of) and a user ID (to perform the
 159 lookup on).  The directory is guaranteed to be a real path.  The plugin
 160 should return an instance of :class:`wizard.user.Info` or ``None``, if
 161 it was unable to perform the lookup.  The function that runs this plugin
 162 is :func:`wizard.user.passwd`.
 163
 164
 165
 166 .. _wizard.user.quota:
 167
 168 ``wizard.user.quota``
 169 ---------------------
 170
 171 Wizard has safeguards for avoiding exceeding user quotas when an
 172 automated upgrade is being performed.  Unfortunately, methods for
 173 enforcing quotas are frequently highly system dependent.  Use this hook
 174 to implement quota usage and limit reporting.  Plugin should be a
 175 function that takes a single required argument ``dir``, which is the
 176 directory to determine the quota for, and return a tuple ``(quota usage,
 177 quota limit)`` or ``None`` if it could not determine quota.  The
 178 function that runs this plugin is :func:`wizard.user.quota`.