=================
 Upgrade Handler
=================

The :term:`upgrade handler` is responsible for executing
:term:`upgrades <upgrade>` - which typically means running some shell
command.  Multiple :term:`upgrade targets <upgrade target>` can be
defined; each with its own command.

The "complete" feature involves making a record of each upgrade
occurrence in the :term:`app database`, as well as capturing the
STDOUT/STDERR streams to file for later review.

For the ``default`` (i.e. local app) upgrade target, output of ``pip
freeze`` is also captured before and after the upgrade runs.  This
allows viewing a package diff e.g. in the web app.

The base class and default upgrade handler is
:class:`wuttjamaican.upgrades.UpgradeHandler`.

The :term:`app handler` is responsible for creating the upgrade
handler via
:meth:`~wuttjamaican.app.AppHandler.get_upgrade_handler()`::

   app = config.get_app()
   handler = app.get_upgrade_handler()