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 Registering plugins without eggs
  21 --------------------------------
  22
  23 To register a plugin without an egg, you need to prepare a special
  24 directory that you will add to your :envvar:`PYTHONPATH`.  Create a
  25 setuptools (not distutils) ``setup.py`` file that sets ``entry_points``
  26 to be the plugins that are to be registered, and then run ``python
  27 setup.py egg_info``.
  28
  29 ``wizard.app``
  30 --------------
  31
  32 Used to register custom applications that Wizard has
  33 support for.  Key is user-visible name of application (e.g.
  34 ``wordpress``) and value is application class (a subclass of
  35 :class:`wizard.app.Application`) to be instantiated to
  36 represent this application (e.g. ``wizard.app.wordpress:Application``)::
  37
  38     [wizard.app]
  39     wordpress = wizard.app.wordpress:Application
  40
  41 For more information on how to create an application, check
  42 :doc:`Creating a Repository <create>`.
  43
  44 .. todo::
  45
  46     Plugins marked with prototype todo messages are not complete yet.
  47
  48 .. _wizard.strategy:
  49
  50 ``wizard.strategy``
  51 -------------------
  52
  53 Used during installation to automatically determine values for
  54 installation parameters the user may have omitted.
  55
  56 .. _wizard.sql.auth:
  57
  58 ``wizard.sql.auth``
  59 --------------------
  60
  61 Used to fill in a user's database authentication credentials if none are
  62 able to be determined from an application's configuration files.  Plugin
  63 should be a function that takes a single required argument ``url``,
  64 which is a :class:`sqlalchemy.engine.url.URL` with partial
  65 authentication information, including a database name, and should return either
  66 ``None`` if it was unable to fill in authentication credentials for the
  67 user, or the completed URL.  Mutating the passed argument and then
  68 returning it is the expected modus operandi of a plugin.  The function
  69 that runs this plugin is :func:`wizard.sql.auth`.
  70
  71 .. _wizard.deploy.web:
  72
  73 ``wizard.deploy.web``
  74 ---------------------
  75
  76 Used to fill in a user's web URL if it is not able to be determined from
  77 an application's configuration files.  Plugin should be a function that
  78 takes a single required argument ``dir``, which is the directory to
  79 determint the web URL(s) for, and return a list or generator of
  80 :class:`urlparse.ParseResult` objects or URL strings of possible web locations
  81 for an application.  The function that runs this plugin is
  82 :func:`wizard.deploy.web`.
  83
  84 .. _wizard.user.email:
  85
  86 ``wizard.user.email``
  87 ---------------------
  88
  89 Used to determine a user's email address.  By default, we use a
  90 heuristic approach;  if your system offers this information in a
  91 canonical form we recommend taking advantage of it.
  92
  93 .. todo:: Prototype
  94
  95 .. _wizard.user.operator:
  96
  97 ``wizard.user.operator``
  98 ------------------------
  99
 100 If Wizard is running as root or as a superuser masquerading as another
 101 user, it is still useful to record who was in front of the screen.  By
 102 default, we check :envvar:`SUDO_USER`; if your system gives more
 103 information we recommend taking advantage of it.
 104
 105 .. todo:: Prototype
 106
 107 .. _wizard.user.passwd:
 108
 109 ``wizard.user.passwd``
 110 ----------------------
 111
 112 If Wizard is running on a system with a network filesystem (such as NFS
 113 or AFS), the standard system ``passwd`` database may not actually
 114 resolve the username from a UID.  Use this hook to implement an
 115 alternative ``passwd`` lookup.
 116
 117 .. todo:: Prototype
 118
 119 .. _wizard.user.quota:
 120
 121 ``wizard.user.quota``
 122 ---------------------
 123
 124 Plugin for :func:`wizard.user.quota`.  Wizard has safeguards for
 125 avoiding exceeding user quotas when an automated upgrade is being
 126 performed.  Unfortunately, methods for enforcing quotas are frequently
 127 highly system dependent.  Use this hook to implement quota usage and
 128 limit reporting.  Plugin should be a function that takes a single
 129 required argument ``dir``, which is the directory to determine the quota
 130 for, and return a tuple ``(quota usage, quota limit)`` or ``(0, None)``
 131 if it could not determine quota.  The function that runs this plugin is
 132 :func:`wizard.user.quota`.