plugin authors should take care to "do no harm" if a plugin is unable to
do anything useful.
+
+
Registering plugins without eggs
--------------------------------
to be the plugins that are to be registered, and then run ``python
setup.py egg_info``.
+
+
``wizard.app``
--------------
For more information on how to create an application, check
:doc:`Creating a Repository <create>`.
-.. todo::
- Plugins marked with prototype todo messages are not complete yet.
-.. _wizard.strategy:
+.. _wizard.install.strategy:
-``wizard.strategy``
--------------------
+``wizard.install.strategy``
+---------------------------
Used during installation to automatically determine values for
-installation parameters the user may have omitted.
+installation parameters the user may have omitted. Plugin should be a
+subclass of :class:`wizard.install.Strategy`. The class that runs this
+plugin is :class:`wizard.install.ArgSchema`.
+
+
.. _wizard.sql.auth:
returning it is the expected modus operandi of a plugin. The function
that runs this plugin is :func:`wizard.sql.auth`.
+.. note::
+
+ If Wizard is able to determine the login credentials from the
+ application's source files, these plugins will not be run.
+
+.. _wizard.sql.drop:
+
+``wizard.sql.drop``
+------------------------------
+
+Used to remove a SQL database, as might be done when an application is
+being uninstalled. Plugin should be a function that takes a single
+required argument ``dsn``, which is a
+:class:`sqlalchemy.engine.url.URL` and should return either ``None`` if
+it was unable to delete the database, or ``True`` in the event of
+success. This is a good plugin to implement if you don't give your
+users ``DROP DATABASE`` permissions, and instead they have to create and
+delete databases through another interface. The function that runs this
+plugin is :func:`wizard.sql.drop`.
+
.. _wizard.deploy.web:
``wizard.deploy.web``
for an application. The function that runs this plugin is
:func:`wizard.deploy.web`.
+.. note::
+
+ If Wizard is able to determine the web URL from the application's
+ source files or database, these plugins will not run.
+
+
+
.. _wizard.user.email:
``wizard.user.email``
Used to determine a user's email address. By default, we use a
heuristic approach; if your system offers this information in a
-canonical form we recommend taking advantage of it.
+canonical form we recommend taking advantage of it. Plugin should be a
+function that takes a single required argument ``name`` and returns a
+string email address corresponding to that user, or ``None`` if it
+was unable to determine an email address. The function that runs this
+plugin is :func:`wizard.user.email`.
+
+.. note::
+
+ If the :envvar:`EMAIL` environment variable is set and we are
+ requesting the current user's email, these plugins will not run.
+
-.. todo:: Prototype
.. _wizard.user.operator:
------------------------
If Wizard is running as root or as a superuser masquerading as another
-user, it is still useful to record who was in front of the screen. By
-default, we check :envvar:`SUDO_USER`; if your system gives more
+user, it is still useful to record who was in front of the screen. The default
+fallback is checking :envvar:`SUDO_USER`; if your system gives more
information we recommend taking advantage of it.
-.. todo:: Prototype
+
.. _wizard.user.passwd:
If Wizard is running on a system with a network filesystem (such as NFS
or AFS), the standard system ``passwd`` database may not actually
resolve the username from a UID. Use this hook to implement an
-alternative ``passwd`` lookup.
+alternative ``passwd`` lookup. Plugin should be a function that takes a
+directory (to determine filesystem off of) and a user ID (to perform the
+lookup on). The directory is guaranteed to be a real path. The plugin
+should return an instance of :class:`wizard.user.Info` or ``None``, if
+it was unable to perform the lookup. The function that runs this plugin
+is :func:`wizard.user.passwd`.
+
-.. todo:: Prototype
.. _wizard.user.quota:
``wizard.user.quota``
---------------------
-Plugin for :func:`wizard.user.quota`. Wizard has safeguards for
-avoiding exceeding user quotas when an automated upgrade is being
-performed. Unfortunately, methods for enforcing quotas are frequently
-highly system dependent. Use this hook to implement quota usage and
-limit reporting. Plugin should be a function that takes a single
-required argument ``dir``, which is the directory to determine the quota
-for, and return a tuple ``(quota usage, quota limit)`` or ``(0, None)``
-if it could not determine quota. The function that runs this plugin is
-:func:`wizard.user.quota`.
+Wizard has safeguards for avoiding exceeding user quotas when an
+automated upgrade is being performed. Unfortunately, methods for
+enforcing quotas are frequently highly system dependent. Use this hook
+to implement quota usage and limit reporting. Plugin should be a
+function that takes a single required argument ``dir``, which is the
+directory to determine the quota for, and return a tuple ``(quota usage,
+quota limit)`` or ``None`` if it could not determine quota. The
+function that runs this plugin is :func:`wizard.user.quota`.