[Checkins] SVN: Sandbox/philikon/zopeproject/trunk/ Added debug.ini for interactive debugging (using z3c.evalexception).

[Philipp von Weitershausen]

Log message for revision 79664:
  Added debug.ini for interactive debugging (using z3c.evalexception).
  

Changed:
  U   Sandbox/philikon/zopeproject/trunk/README.txt
  U   Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/buildout.cfg_tmpl
  A   Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/debug.ini_tmpl

-=-
Modified: Sandbox/philikon/zopeproject/trunk/README.txt
===================================================================
--- Sandbox/philikon/zopeproject/trunk/README.txt	2007-09-15 10:00:24 UTC (rev 79663)
+++ Sandbox/philikon/zopeproject/trunk/README.txt	2007-09-15 10:48:57 UTC (rev 79664)
@@ -117,6 +117,11 @@
   You may also define WSGI middlewares here.  Invoke ``bin/paster
   serve`` with this file as an argument.
 
+``debug.ini``
+  Alternate configuration for PasteDeploy_ that configures a
+  middleware which intercepts exceptions for interactive debugging.
+  See `Debugging exceptions`_ below.
+
 ``zope.conf``
   This file will be read by the application factory in
   ``myzopeproj/application.py``.  Here you can define which ZCML file
@@ -227,6 +232,9 @@
 Debugging
 =========
 
+The interactive debug prompt
+----------------------------
+
 Occasionally, it is useful to be able to interactively debug the state
 of the application, such as walking the object hierarchy in the ZODB
 or looking up components manually.  This can be done with the
@@ -244,7 +252,34 @@
   >>> list(root.keys())
   [u'folder', u'file']
 
+Debugging exceptions
+--------------------
 
+In case your application fails with an exception, it can be useful to
+inspect the circumstances with a debugger.  This is possible with the
+``z3c.evalexception`` WSGI middleware.  When an exception occurs in
+your application, stop the process and start it up again, now using
+the ``debug.ini`` configuration file::
+
+  $ bin/paster serve debug.ini
+
+When you now repeat the steps that led to the exception, you will see
+the relevant traceback in your browser, along with the ability to view
+the corresponding source code and to issue Python commands for
+inspection.
+
+If you prefer the Python debugger pdb_, replace ``ajax`` with ``pdb``
+in the WSGI middleware definition in ``debug.ini``::
+
+  [filter-app:main]
+  use = egg:z3c.evalexception#pdb
+  next = zope
+
+Note: Even exceptions such as Unauthorized (which normally leads to a
+login screen) or NotFound (which normally leads to an HTTP 404
+response) will trigger the debugger.
+
+
 Changes
 =======
 
@@ -320,4 +355,5 @@
 .. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
 .. _PasteDeploy: http://pythonpaste.org/deploy/
 .. _listed on the Python Cheeseshop: http://cheeseshop.python.org/pypi?:action=browse&c=515
+.. _pdb: http://docs.python.org/lib/module-pdb.html
 .. _grokproject: http://cheeseshop.python.org/pypi/grokproject

Modified: Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/buildout.cfg_tmpl
===================================================================
--- Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/buildout.cfg_tmpl	2007-09-15 10:00:24 UTC (rev 79663)
+++ Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/buildout.cfg_tmpl	2007-09-15 10:48:57 UTC (rev 79664)
@@ -8,6 +8,7 @@
 [app]
 recipe = zc.recipe.egg
 eggs = ${egg}
+       z3c.evalexception>=2.0
        Paste
        PasteScript
        PasteDeploy

Copied: Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/debug.ini_tmpl (from rev 79656, Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/deploy.ini_tmpl)
===================================================================
--- Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/debug.ini_tmpl	                        (rev 0)
+++ Sandbox/philikon/zopeproject/trunk/zopeproject/zope_deploy/debug.ini_tmpl	2007-09-15 10:48:57 UTC (rev 79664)
@@ -0,0 +1,13 @@
+[filter-app:main]
+# Change the last part from 'ajax' to 'pdb' for a post-mortem debugger
+# on the console:
+use = egg:z3c.evalexception#ajax
+next = zope
+
+[app:zope]
+use = egg:${egg}
+
+[server:main]
+use = egg:Paste#http
+host = 127.0.0.1
+port = 8080