The GearBox Toolkit

The GearBox toolkit is a set of commands available since TurboGears 2.3 that replaced the paster command previously provided by pylons.

GearBox provides commands to create new full stack projects, serve PasteDeploy based applications, initialize them and their database, run migrations and start an interactive shell to work with them.

By default launching gearbox without any subcommand will start the interactive mode. This provides an interactive prompt where gearbox commands, system shell commands and python statements can be executed. If you have any doubt about what you can do simply run the help command to get a list of the commands available (running help somecommand will provide help for the given sub command).

To have a list of all the available commands simply run gearbox --help


The gearbox quickstart command creates a new full stack TurboGears application, just provide the name of your project to the command to create a new one:

$ gearbox quickstart myproject

The quickstart command provides a bunch of options to choose which template engine to use, which database engine to use various other options:

optional arguments:
  -a, --auth            add authentication and authorization support
  -n, --noauth          No authorization support
  -m, --mako            default templates mako
  -j, --jinja           default templates jinja
  -k, --kajiki          default templates kajiki
  -g, --geo             add GIS support
  -p PACKAGE, --package PACKAGE
                        package name for the code
  -s, --sqlalchemy      use SQLAlchemy as ORM
  -i, --ming            use Ming as ORM
  -x, --nosa            No SQLAlchemy
  --disable-migrations  disable sqlalchemy-migrate model migrations
  --enable-tw1          use toscawidgets 1.x in place of 2.x version
  --skip-tw             Disables ToscaWidgets
  --skip-genshi         Disables Genshi default template
  --minimal-quickstart  Throw away example boilerplate from quickstart project


The gearbox setup-app command runs the websetup.setup_app function of your project to initialize the database schema and data.

By default the setup-app command is run on the development.ini file, to change this provide a different one to the --config option:

$ gearbox setup-app -c production.ini


The gearbox serve command starts a PasteDeploy web application defined by the provided configuration file. By default the development.ini file is used, to change this provide a different one to the --config option:

$ gearbox serve -c production.ini --reload

The serve command provides a bunch of options to start the serve in daemon mode, automatically restart the application whenever the code changes and many more:

optional arguments:
                        application config file to read (default:
  -n NAME, --app-name NAME
                        Load the named application (default main)
                        Use the named server.
  --server-name SECTION_NAME
                        Use the named server as defined in the configuration
                        file (default: main)
  --daemon              Run in daemon (background) mode
  --pid-file FILENAME   Save PID to file (default to if running in
                        daemon mode)
  --reload              Use auto-restart file monitor
  --reload-interval RELOAD_INTERVAL
                        Seconds between checking files (low number can cause
                        significant CPU usage)
  --monitor-restart     Auto-restart server if it dies
  --status              Show the status of the (presumably daemonized) server
  --user USERNAME       Set the user (usually only possible when run as root)
  --group GROUP         Set the group (usually only possible when run as root)
  --stop-daemon         Stop a daemonized server (given a PID file, or default

Changing HTTP Server

gearbox serve will look for the [server:main] configuration section to choose which server to run and one which port and address to listen.

Any PasteDeploy compatible server can be used, by default the egg:gearbox#wsgiref one is used, which is single threaded and based on python wsgiref implementation.

This server is idea for debugging as being single threaded removes concurrency issues and keeps around request local data, but should never be used on production.

On production system you might want to use egg:gearbox#cherrypy or egg:gearbox#gevent servers which run the application on CherryPy and Gevent, it is also possible to use other servers like Waitress (egg:waitress#main) if available.


The gearbox tgshell command will load a TurboGears application and start an interactive shell inside the application.

The application to load is defined by the configuration file, by default development.ini is used, to load a different application or under a different configuration provide a configuration file using the --config option:

$ gearbox tgshell -c production.ini

The tgshell command provides an already active fake request which makes possible to call functions that depend on tg.request, it is also provided an app object through which is possible to make requests:

$ gearbox tgshell
TurboGears2 Interactive Shell
Python 2.7.3 (default, Aug  1 2012, 05:14:39)
[GCC 4.6.3]

  All objects from myapp.lib.base are available
  Additional Objects:
  wsgiapp    -  This project's WSGI App instance
  app        -  WebTest.TestApp wrapped around wsgiapp

>>> tg.request
<Request at 0x3c963d0 GET http://localhost/_test_vars>
>>> app.get('/data.json').body
'{"params": {}, "page": "data"}'
>>> model.DBSession.query(model.User).first()
<User: name=manager,, display=Example manager>

Running Scripts from Command Line

You will notice that writing a python script that depends on TurboGears and running from the command line will fail with an error.

Suppose you have a script like:

import tg
print 'Hello From', tg.request.path

Saving it as and running it will fail with TurboGears complaining about a missing context:

$ python
Hello From
Traceback (most recent call last):
  File "", line 2, in <module>
    print 'Hello From', tg.request._path
  File "/Users/amol/wrk/tg/tg2/tg/support/", line 19, in __getattr__
    return getattr(self._current_obj(), attr)
  File "/Users/amol/wrk/tg/tg2/tg/", line 214, in _current_obj
    return getattr(context,
  File "/Users/amol/wrk/tg/tg2/tg/support/", line 19, in __getattr__
    return getattr(self._current_obj(), attr)
  File "/Users/amol/wrk/tg/tg2/tg/support/", line 72, in _current_obj
    'thread' % self.____name__)
TypeError: No object (name: context) has been registered for this thread

That because we are trying to access the current request (tg.request) but we are outside of a web application, so no request exists.

TGShell command solves this problem as it uses same features described in Testing Outside Controllers to run any script inside a fake request:

$ gearbox tgshell
15:30:13,925 INFO  [tgext.debugbar] Enabling Debug Toolbar
15:30:13,953 INFO  [auth] request classification: browser
15:30:13,953 INFO  [auth] -- repoze.who request started (/_test_vars) --
15:30:13,953 INFO  [auth] no identities found, not authenticating
15:30:13,953 INFO  [auth] no challenge required
15:30:13,953 INFO  [auth] -- repoze.who request ended (/_test_vars) --
Hello From /_test_vars

So through TGShell it’s also possible to run turbogears based scripts like you were inside an HTTP request for a controller.

Adding your own command

To add commands to available gearbox commands, add them to your project entry points under the gearbox.commands group. Here is en example with setuptools:

    # [...]
        'gearbox.commands': [
            'my_command = sample_app.my_commands_module.my_command_module:MyCommandClass'

Where your command class extend gearbox.command.Command:

# -*- coding: utf-8 -*-
from gearbox.command import Command

class MyCommandClass(Command):
    def take_action(self, parsed_args):
        print('Hello world')