How-to: Create a new SchevoGears project

This how-to covers the bare minimum needed to create a new TurboGears project that incorporates a Schevo database.

Requirements

Schevo >= 3.0b3 and SchevoGears >= 1.0a2dev:

easy_install Schevo SchevoGears==dev

This document was written against the 1.0b1 release TurboGears. It is automatically installed when installing SchevoGears as above, but you can also manually install it:

easy_install TurboGears

Create quickstart project

For the purposes of this how-to, we'll create a project called MyApp.

Start by using the built-in quickstart command included with TurboGears. Give the project a name. For now, do not activate identity as there is no Schevo-based identity provider in SchevoGears 1.0a1:

$ tg-admin quickstart
Enter project name: MyApp
Enter package name [myapp]:
Do you need Identity (usernames/passwords) in this project? [no]

Once the project is created, move into its top-level directory and activate it as a Python egg:

$ cd MyApp
$ python setup.py develop

Create empty schema

Create the directory structure that will contain the schema subpackage:

$ mkdir myapp/schema
$ touch myapp/schema/__init__.py

Create a myapp/schema/schema_001.py file and place the Schevo schema preamble at the top. Nothing else is necessary at this point:

# All Schevo schema modules must have these lines.
from schevo.schema import *
schevo.schema.prep(locals())

Create a database

Use the schevo command-line utility to create a new database based on the empty schema:

$ schevo db create --app=myapp myapp-dev.db

Associate database with app configuration

Open the dev.cfg file. Add the following line to the [global] section to tell where the Schevo database file is located:

schevo.dbfile='myapp-dev.db'

Associate database with model module

Open the myapp/model.py file. Add the following two lines to open the Schevo database file when your project's myapp.model module is imported:

from schevogears.database import package_database
db = package_database()

Add reference to database in a template

Open the myapp/templates/welcome.kid file. Below the final paragraph and above the </body> closing tag, insert these lines:

<?python
from myapp.model import db
?>
${repr(db)}

Start the development server and test

Run the start-myapp.py script to start the development web server. Browse to http://localhost:8080 to view the welcome page.

If you see the following somewhere on the page, you've successfully completed the steps in this how-to and can now begin building your database schema and web app!

<Database 'Schevo Database' :: V 1>

Helpful reminders

  • When you change any code in your app other than your database schema, the CherryPy autoreloader used by TurboGears will reload the development web server. SchevoGears assists in this process by closing and re-opening your database.

  • When you change your database schema, the CherryPy autoreloader will not trigger. You must instead use Ctrl+C to stop the development web server, then update the schema used by your database using the following command, then re-start the web server:

    $ schevo db update --app=myapp myapp-dev.db

  • You can get to your app's open database from any module by using this import:

    from myapp.model import db

  • Projects are under way as of this writing to provide open source Schevo-aware TurboGears widgets and controllers, but as of this writing, none have been publicly announced. Schevo uses an API that differs wildly from that used by data-aware widgets included with TurboGears, so at the moment you are on your own.