============================================
04: Easier Development with ``debugtoolbar``
============================================

Error-handling and introspection using the ``pyramid_debugtoolbar``
add-on.

Background
==========

As we introduce the basics we also want to show how to be productive in
development and debugging. For example, we just discussed template
reloading and earlier we showed ``--reload`` for application reloading.

``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes
several tools available in your browser. Adding it to your project
illustrates several points about configuration.

Objectives
==========

- Install and enable the toolbar to help during development

- Explain Pyramid add-ons

- Show how an add-on gets configured into your application

Steps
=====

#. First we copy the results of the previous step, as well as install
   the ``pyramid_debugtoolbar`` package:

   .. code-block:: bash

    $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
    $ $VENV/bin/python setup.py develop
    $ $VENV/bin/easy_install pyramid_debugtoolbar


#. Our ``debugtoolbar/development.ini`` gets a configuration entry for
   ``pyramid.includes``:

   .. literalinclude:: debugtoolbar/development.ini
    :language: ini
    :linenos:

#. Run the WSGI application with:

   .. code-block:: bash

    $ $VENV/bin/pserve development.ini --reload

#. Open http://localhost:6543/ in your browser. See the handy
   toolbar on the right.

Analysis
========

``pyramid_debugtoolbar`` is a full-fledged Python package,
available on PyPI just like thousands of other Python packages. Thus we
start by installing the ``pyramid_debugtoolbar`` package into our
virtual environment using normal Python package installation commands.

The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on,
which means we need to include its add-on configuration into our web
application. We could do this with imperative configuration in
``tutorial/__init__.py`` by using ``config.include``. Pyramid also
supports wiring in add-on configuration via our ``development.ini``
using ``pyramid.includes``. We use this to load the configuration for
the debugtoolbar.

You'll now see an attractive (and collapsible) menu in the right of
your browser, providing introspective access to debugging information.
Even better, if your web application generates an error,
you will see a nice traceback on the screen. When you want to disable
this toolbar, no need to change code: you can remove it from
``pyramid.includes`` in the relevant ``.ini`` configuration file (thus
showing why configuration files are handy.)

Note that the toolbar mutates the HTML generated by our app and uses jQuery to
overlay itself.  If you are using the toolbar while you're developing and you
start to experience otherwise inexplicable client-side weirdness, you can shut
it off by commenting out the ``pyramid_debugtoolbar`` line in
``pyramid.includes`` temporarily.

.. seealso:: See Also: :ref:`pyramid_debugtoolbar <toolbar:overview>`