Error-handling and introspection using the pyramid_debugtoolbar add-on.
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.
First we copy the results of the previous step, as well as install the pyramid_debugtoolbar package:
$ 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
[app:main] use = egg:tutorial pyramid.includes = pyramid_debugtoolbar [server:main] use = egg:pyramid#wsgiref host = 0.0.0.0 port = 6543 # Begin logging configuration [loggers] keys = root, tutorial [logger_tutorial] level = DEBUG handlers = qualname = tutorial [handlers] keys = console [formatters] keys = generic [logger_root] level = INFO handlers = console [handler_console] class = StreamHandler args = (sys.stderr,) level = NOTSET formatter = generic [formatter_generic] format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s # End logging configuration
Run the WSGI application with:
$ $VENV/bin/pserve development.ini --reload
Open http://localhost:6543/ in your browser. See the handy toolbar on the right.
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.
See Also: pyramid_debugtoolbar