===================
Debugging Templates
===================

In order to keep templates debuggable you have to do some additional work on
the application side. The traceback module that comes with python currently
does not support the `__loader__` hook which is used by Jinja to provide
templates. Although the import system was implemented three Python versions
ago the default traceback system still doesn't support it.

However most of the extended web development traceback modules have support
for `__loader__`.  Either directly or via the linecache module:

-  `Werkzeug Debugging Middleware`_
-  `Django`_
-  `cgitb`_
-  `EvalException`_

To enable debugging you have to use one of those debugging systems or
implement your own one with support for `__loader__`.

The python implementation of the jinja debugger can only translate the first
exception in a traceback which can lead to problematic results.  If you have
the extended debugger c extension compiled (default on unix systems but only
available on Windows if you have a VisualStudio 2003 installation) all frames
in the traceback will point to the correct linenumbers of the templates.


.. _Werkzeug Debugging Middleware: http://werkzeug.pocoo.org/
.. _Django: http://www.djangoproject.com/
.. _cgitb: http://docs.python.org/lib/module-cgitb.html
.. _EvalException: http://pythonpaste.org/module-paste.evalexception.html
