TurboGears provides a suite of tools for working with projects by adding several commands to the Python command line tool paster. A few will be touched upon in this tutorial. (Check the Command Line Reference for a full listing.) The first tool you’ll need is quickstart which initializes a TurboGears project. Go to a command line window and run the following command:
$ paster quickstart
You’ll be prompted for the name of the project (this is the pretty name that human beings would appreciate), and the name of the package (this is the less-pretty name that Python will like). Here’s what our choices for this tutorial look like:
$ paster quickstart
Enter project name: Wiki 20
Enter package name [wiki20]: wiki20
Do you need authentication and authorization in this project? [yes] no
We recommend you use the names given here: this documentation looks for files in directories based on these names.
Now paster will spit out a bunch of stuff:
Selected and implied templates:
TurboGears2#turbogears2
TurboGears 2.0 Template
...etc...
running compile_catalog
1 of 1 messages (100%) translated in 'wiki20/i18n/ru/LC_MESSAGES/wiki20.po'
compiling catalog 'wiki20/i18n/ru/LC_MESSAGES/wiki20.po' to 'wiki20/i18n/ru/LC_MESSAGES/wiki20.mo'
This creates a directory tree Wiki-20 just below your current directory. We have just one more stage of installation to complete:
$ cd Wiki-20
$ python setup.py develop
This will emit some output, and hopefully finish with success:
(tg2env)localhost~/python/turbogears/tg2env/Wiki-20$ python setup.py develop
running develop
running egg_info
writing requirements to Wiki_20.egg-info/requires.txt
writing Wiki_20.egg-info/PKG-INFO
writing top-level names to Wiki_20.egg-info/top_level.txt
writing dependency_links to Wiki_20.egg-info/dependency_links.txt
writing entry points to Wiki_20.egg-info/entry_points.txt
writing paster_plugins to Wiki_20.egg-info/paster_plugins.txt
reading manifest file 'Wiki_20.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
writing manifest file 'Wiki_20.egg-info/SOURCES.txt'
running build_ext
Creating /home/user/python/turbogears/tg2env/lib/python2.5/site-packages/Wiki-20.egg-link (link to .)
Adding Wiki-20 0.1dev to easy-install.pth file
Installed /home/user/python/turbogears/tg2env/Wiki-20
Processing dependencies for Wiki-20==0.1dev
Searching for repoze.tm2==1.0a4
Best match: repoze.tm2 1.0a4
Processing repoze.tm2-1.0a4-py2.5.egg
repoze.tm2 1.0a4 is already the active version in easy-install.pth
...
...
Finished processing dependencies for Wiki-20==0.1dev
Now we’re ready to start!
The current directory Wiki-20 is the root directory of your project.
All imports of project code are made relative to this directory, and all html templates are called from this directory too. All files we discuss will be relative to this root directory.
Some of the files you’ll find in your root directory after you’ve quickstarted a new project include:
The main subdirectories we’ll be concerned with are model, templates and controllers.
TurboGears follows the Model-View-Controller paradigm (a.k.a. “MVC”), as do most modern web frameworks like Rails, Cake, Struts, etc.
MVC | Interface | Turbogears Defaults | files you’ll be editing |
---|---|---|---|
Models | Database | SQLAlchemy | wiki20/model/*.py |
Views | Webpage | Genshi | wiki20/templates/*.html |
Controllers | User/Content | Turbogears | wiki20/controllers/root.py |
The file development.ini that paster has written to your root directory contains a default setup, including connection to an sqlite file database. You’re free to change your settings to use another database, host url, etc. - edit as you please.
paster provides a simple mechanism for running a TurboGears project. From inside the Wiki-20 directory, the root directory of your project, run the command:
$ paster serve --reload development.ini
The --reload flag means that changes that you make in the project will automatically cause the server to restart itself, loading the changes. This way you immediately see updated results.
You can access your models from within the python/ipython shell by typing:
$ paster shell development.ini
from your root directory. If ipython is installed within your virtual environment, it will be the default python shell.
You now have a working project! Point your browser to http://localhost:8080, and you’ll see a nice welcome page:
There are some links on this page to TurboGears documentation. Spend some time exploring what’s there.
Now we’ll look at the two files directly involved in displaying this welcome page: