Command Line Reference

TurboGears2 delegates its command line tasks to Paste. TG1.x uses the built-in command tgadmin which was dropped in favor of the more robust Paste infrastructure.

What is PasteScript?

PasteScript is a part of the Paste group of libraries, which provides the very basic foundation on which TurboGears and Pylons are built. You can think of Paste as a very useful group of things.

As for PasteScript it is composed of two parts Templates and Commands, the first takes care of code generation tasks (like quickstart), the second is an extensible command line utility (like tginfo)

If you are interested in learning how to build your own Paster command please visit http://pythonpaste.org/script/developer.html

How Does It Integrate With TurboGears 2?

PasteScript provides a single command-line script named paster which is built to be self-explanatory. Try it out on the command line: it should give you a big list of commands. There is also a paster help <command> command that will give you additional information about all commands that it provides.

Using a setuptools mechanism known as “entry point” TurboGears, as well as any other project that uses PasteScript, is able to add extensions to the paster command; for example if you execute paster with no parameters you will see a “TurboGears2” section.

What are the TurboGears commands?

Please note that not all paster commands are expected to work with a TurboGears 2.1 project. However, if you experience an error using paster we encourage you to report it. Below is a list of the most important commands you will use in your journey in the world of TurboGears 2.1. Be sure to run paster help on each of them to get all the possible command line switches.

paster command action
paster quickstart <project_name> initialize new project
paster serve <config_file> serve project configured in <config_file>
paster tginfo list tg files in current path
paster shell <config_file> start python shell, loading project models
paster setup-app <config_file> initialize project using config_file

paster quickstart

This is probably the first command you will encounter when developing on TurboGears, it will create a base project for you with everything you need to get started and explanations for everything. In case you are wondering this is a small wrapper around paster create to provide a TG1-like command.

paster serve

This is used to start the built-in server. This is a very robust implementation (multi-threaded, SSL support, etc.) which means several people use it in production. That said, you should take a look at our Deployment docs. The most common usage for this command is:

$ paster serve --reload development.ini

The above command will enable the reloading of the server every time you save a file, which is a very nice feature :)

paster tginfo

This command is designed to display a rather big chunk of information regarding your TurboGears installation, and it’s designed to troubleshoot installation problems. Therefore it should be the first thing you should run to be certain your system is healthy.

paster shell

This starts a python shell with your TurboGears application loaded. The most important feature here is that your model is also loaded, therefore you can experiment with your database.

Note

Changes made to your database from within paster shell are encapsulated in a transaction. In other words, your changes won’t be saved unless you commit:

import transaction
transaction.commit()

paster setup-app

setup-app provides two crucial pieces of functionality.

  1. Set up your database schema.
  2. Add bootstrap data to your database.

Your project will have a folder called websetup which contains schema.py and bootstrap.py. Each of these can be customized to add additional functionality to your bootstrapping process. For instance, if you have additional default users you would like added, you would add them in at the bottom of bootstrap.py inside the bootstrap() function, before the transaction.commit(). The command looks something like this:

paster setup-app development.ini