.. note:: **The information on this page is obsolete, incomplete or incorrect and left here only for reference
  and has not been ported to the new documentation wiki.**

  Please refer to the `TurboGears documentation wiki`_ for up-to-date documentation.

.. _turbogears documentation wiki: http://docs.turbogears.org/

Paste & Turbogears Basic Flow
==============================

The following shows the default wsgi stack when running TurboGears with
Paste.  Note that the particular middleware might change depending
on config values *(right now, these are in the [app:main] section
of the config file.  Does that change?)*

Here's the default wsgi_ call stack:

``paste.httpserver`` basically just python's BaseHTTPServer.  It
gets the request in and calls the top of the wsgi_ stack.

``paste.deploy.config`` adds ``paste.config`` (copy of config data) to
the wsgi_ environment.

*Note:* there are several debug related middlewares which may
be inserted here by config parameters.  See:
``rhubarbtart/paste_templates/rhubarbtart/docs/devel_config.ini_tmpl``

``paste.session`` wsgi_ session middleware.  Looks up session data
in cookies and adds "paste.session.factory" to the wsgi_
environment.  (enabled in conf with ``use_session`` set to true)

``paste.recursive`` this allows "internal redirects" and "include"
calling.  Adds ``paste.recursive.forward`` and ``paste.recursive.include``
to the wsgi_ environment. (enabled in conf with 'use_recursive')

``paste.httpexceptions`` Handles basic http exceptions.  If downstream
wsgi_ apps throws (for instance) an ``HTTPMovedPermanently`` exception,
then this module handles the exception and fills out the headers
appropriate for the exception.
    
``rhubarbtart.__init__`` Create cherry-py-like request and response objects,
then call the approprite method based on the url.

RhubarbTart Details
-------------------

The RhubarbTart object that gets called is really the root TurboGears
controller.  The ``_run_app`` method matches the url from PATH_INFO_, to
nodes in the root TurboGears controller.  When it hits a node which is a
wsgi_ app (for instance, if a sub-controller under TurboGears is a
RootController rather than a Controller), then it moves the "swollowed"
part of PATH_INFO_ to SCRIPT_NAME_ and immediately calls the root
controller.

If it doesn't find any wsgi_application controllers at all, then it
calls the node furthest down on the path that has the "expose" 
property set.

So, if our nodes look like:

.. image:: http://trac.turbogears.org/turbogears/attachment/wiki/RhubarbStack/flow1.png?format=raw

Note that boxes are "root" controllers, ovals are regular
controllers and diamonds are methods.

Processing the url ``/tg_blog/index/blah/boom`` will match
the ``tg_blog`` and ``index`` nodes (neither of which is a
wsgi_ application), so it ends up calling the ``index`` method.

Processing the url ``/members/member_list/get_member`` will first get to
``members`` which is a wsgi_ application, so it's immediately called.
Note that SCRIPT_NAME_ environment now has ``/members`` in it and
PATH_INFO_ has ``/member_list/get_member``.  Now ``members`` happens to
also be a TurboGears RootController so the same RhubarbTart call happens
all over again, this time with ``members`` as the root.  This time, the
url matches down to the ``get_member`` method and it is called.

Just as a note, this low-level flow seems to be changing...

.. _wsgi: http://www.python.org/peps/pep-0333.html
.. _PATH_INFO: http://www.python.org/peps/pep-0333.html#environ-variables
.. _SCRIPT_NAME: http://www.python.org/peps/pep-0333.html#environ-variables