=======================
Using the Zope Debugger
=======================

Introduction
------------

Zope3 includes a mechanism to debug an object publishing request,
similar to the Zope2
`debug mechanism`_.

.. _debug mechanism:
   http://www.zope.org/Members/mcdonc/HowTos/UsingTheZopeDebugger

Setting up Environment
----------------------

Setup your PYTHONPATH environment variable to include src. ie (unix
bash syntax)::

  cd Zope3
  export PYTHONPATH=$PWD/src:$PYTHONPATH

To start interacting with the debugger you need to initialize the zope
application::

  $ python2.3
  >>> from zope.app.debug import Debugger
  >>> debugger = Debugger()


Note that you can pass a database file name and a site ZCML file to
the debugger:

  >>> Debugger('path/to/zodb/', 'path/to/site.zcml')

But you can generally let the debugger figure out where they are.

XXX In the future, the debugger should have it's own ZConfig file.


Using the Debugger
------------------

There are several methods you can call on the application object for
testing purposes.

Publish
  The `publish()` method executes a request as the publisher would and
  prints the response headers and body::

     >>> debugger.publish(path='/folder/content_object')

Run
  The `run()` method executes a request with the publisher's normal
  error handling disabled and without outputting anything.  This is
  useful for use with Python's post-mortem.

     >>> debugger.run(path='/folder/content_object')
     # an exception is raised
     >>> import pdb; pdb.pm()
     # enters the python post-mortem debugger

Debug
  The `debug()` method starts up the publisher in the python debugger,
  with an extra convenience break point, setup just before the
  published object call::

    >>> debugger.debug(path='/folder/content_object')
    * Type c<cr> to jump to published object call.
    pdb>

Arguments
~~~~~~~~~

All of the debugger object's debug methods take optional arguments,
the more common/useful ones...

`path`
  the URL path to debug

`basic`
  user:password used for HTTP basic auth (it will be base64 encoded by
  the debug method).

Accessing objects (without the debugger)
----------------------------------------

You can use the application object to open a database connection to
access your objects.  If the application object is called, it opens a
database connection and fetches the root object::

   root = debugger.root()

For example, to list the objects in the root folder::

   print list(root)

Also note that, after initializing the application, by creating the
root object, you can access any global services setup during
initialization.
