Table Of Contents

Behind The Scenes

This page explains some of inner workings of TurboGears. This may be interesting to users wanting to extend TurboGears or for prospective core TG developers. While we try to be as accurate as we can and as detailed as necessary, the definite reference is always the source!

Two, One, Zero, Lift off! - The TurboGears Launch Sequence

What happens when you start a TurboGears application until it is ready to process requests? How are the bits and pieces that make up the TurboGears framework assembled together? Please read the following section to learn more than you probably wanted to know!

  1. Somebody (you, an init script, supervisor, mod_wsgi) runs the application’s start script. It simply imports the start function from the command module of the app and runs it.

  2. The start function looks for a deployment configuration file in several places (see comments in command.py) and loads it, as well as the configuration from the config/*.cfg files in your app’s package. Parsing the configuration also triggers setting up the logging handlers etc.

  3. It imports the Root controller class from the app’s controllers module, instantiates it, and passes it to the turbogears. start_server function (imported from turbogears.startup).

  4. When the startup module is imported, it replaces the CherryPy auto-reloader with TurboGears’ own implementation.

  5. start_server mounts the root controller to the CherryPy object tree and starts the CherryPy server.

  6. This triggers calling the turbogears.startup. startTurboGears function, because it is listed in the on_start_server_list attribute of the CherryPy server. This function handles the remaining initialization tasks (in given order):

    • Turns off CherryPy’s debug logging filter (which CherryPy normally turns on by default in development mode).

    • Adds a static filter for TurboGears’s static files (URL "/tg_static").

    • Adds a static filter for TurboGears’s JavaScript files (URL "/tg_js").

    • Adds the CherryPy decoding filter to the root URL ("/") if enabled in the configuration.

    • Loads the template engines and the base templates.

    • Adds the following CherryPy request filters to the root controller:

      • VirtualPathFilter
      • EndTransactionsFilter
      • NestedVariablesFilter
      • SafeMultipartFilter
    • When in development mode, registers the server with the Bonjour framework, if available.

    • Calls turbogears.database. bind_metadata when using SQLAlchemy.

    • Loads all turbogears.extensions entry points and calls their start_extension method. The standard extensions included with TurboGears are:

      Visit
      • Replaces the CherryPy decoding filter with TurboGears’ own implementation, /MonkeyDecodingFilter.
      • Loads a “visit manager”, which creates the visit data model if necessary.
      • Loads any registered visit plugins.
      • Adds the VisitFilter to the root controller.
      Identity

      Loads the IdentityVisitPlugin, which creates the identity data model if necessary, instantiates an identity provider, and registers itself as a visit plugin.

    • Calls the callables registered in turbogears.call_on_startup.

    • Starts the TurboGears scheduler if enabled.

  • Now the TurboGears application is ready to serve requests...

A Microsecond in the Life of a TurboGears Request

  1. The server creates a request and response object, registers with CherryPy and runs it, passing in request method, query, headers and the request body.
  2. CherryPy parses the headers and looks up the request handler, calls any before_handler filters, and then calls the request handler.
  3. To be completed...