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     The below plugins are not implemented by Wizard yet.
  47
  48 ``wizard.strategy``
  49 -------------------
  50
  51 Used during installation to automatically determine values for
  52 installation parameters the user may have omitted.
  53
  54 ``wizard.sql.auth``
  55 --------------------
  56
  57 Used to fill in a user's database authentication credentials if none are
  58 able to be determined from an application's configuration files.
  59
  60 .. todo:: Prototype
  61
  62 ``wizard.user.email``
  63 ---------------------
  64
  65 Used to determine a user's email address.  By default, we use a
  66 heuristic approach;  if your system offers this information in a
  67 canonical form we recommend taking advantage of it.
  68
  69 .. todo:: Prototype
  70
  71 ``wizard.user.operator``
  72 ------------------------
  73
  74 If Wizard is running as root or as a superuser masquerading as another
  75 user, it is still useful to record who was in front of the screen.  By
  76 default, we check :envvar:`SUDO_USER`; if your system gives more
  77 information we recommend taking advantage of it.
  78
  79 .. todo:: Prototype
  80
  81 ``wizard.user.passwd``
  82 ----------------------
  83
  84 If Wizard is running on a system with a network filesystem (such as NFS
  85 or AFS), the standard system ``passwd`` database may not actually
  86 resolve the username from a UID.  Use this hook to implement an
  87 alternative ``passwd`` lookup.
  88
  89 .. todo:: Prototype