Creating Project Structure

Hint

This tutorial targets TurboGears 2.5.1 on Python 3 and follows the project layout generated by the current gearbox quickstart command.

Setting up our Environment

If this is your first TurboGears2 project you need to create an environment and install the TurboGears2 web framework to make the development commands available.

Completed version of this tutorial is available on http://runnable.com/U8P0CQTKHwNzQoYs/turbogears-wikier-tutorial-for-python.

If you want to play around with this tutorial without installing TurboGears on your computer you can freely edit the Runnable version.

Creating the Environment

First we are going to create a Virtual Environment where we will install the framework. This helps keeping our system clean by not installing the packages system-wide. Python 3 provides the venv module for this:

$ python3 -m venv tgenv
$ . tgenv/bin/activate

If our environment got successfully created and activated we should end up with a prompt that looks like:

(tgenv)$

Installing TurboGears2

TurboGears2 can be quickly installed by installing the TurboGears2 development tools. This will install TurboGears2 itself and a bunch of commands useful when developing TurboGears applications:

(tgenv)$ python -m pip install tg.devtools

Creating the Project

If the install correctly completed the gearbox quickstart command should be available in your virtual environment:

(tgenv)$ gearbox quickstart wikir

This will create a project called wikir with the default Kajiki template engine, SQLAlchemy database support, and authentication. TurboGears2 projects usually share a common structure, which should look like:

wikir
├── __init__.py
├── config       <-- Where project setup and configuration is located
├── controllers  <-- All the project controllers, the logic of our web application
├── i18n         <-- Translation files for the languages supported
├── lib          <-- Utility python functions and classes
├── model        <-- Database models
├── public       <-- Static files like CSS, javascript and images
├── templates    <-- Templates exposed by our controllers
├── tests        <-- Tests
└── websetup     <-- Functions to execute at application setup like creating tables, a standard user and so on.

Installing Project and its Dependencies

Before we can start our project and open it into a browser we must install the project itself and the dependencies declared by the quickstart. This can easily be achieved by installing the project in editable mode:

(tgenv)$ cd wikir
(tgenv)$ python -m pip install -e .

Project dependencies are specified inside pyproject.toml in the [project].dependencies list. Default project dependencies should look like:

[project]
dependencies = [
  "TurboGears2 >= 2.5.0",
  "Beaker >= 1.8.0",
  "Kajiki >= 0.6.3",
  "zope.sqlalchemy >= 1.2",
  "sqlalchemy < 3.0",
  "alembic",
  "repoze.who",
  "WebHelpers2",
  "Babel >= 2.16.0",
]

Kajiki is the template engine our application is going to use. The zope.sqlalchemy, sqlalchemy, and alembic dependencies provide the SQLAlchemy based database layer and migrations. repoze.who provides the authentication layer, while Beaker, WebHelpers2, and Babel support sessions, template helpers, and internationalization.

Later sections add tutorial-specific dependencies such as the TurboGears admin extension and Markdown. When those dependencies are added to pyproject.toml, run python -m pip install -e . again so the active environment sees them.

Serving our Project

Note

If you skipped the python -m pip install -e . command you might end up with an import or distribution error for wikir or one of its optional dependencies. Re-run the editable install whenever you change the dependency list in pyproject.toml.

You should now be able to start the newly created project with the gearbox serve command:

(tgenv)$ gearbox serve --reload
Starting subprocess with file monitor
Starting server in PID 32797.
serving on http://127.0.0.1:8080

Note

The –reload option makes the server restart whenever a file is changed, this greatly speeds up the development process by avoiding having to manually restart the server whenever we need to try our changes.

Pointing your browser to http://127.0.0.1:8080/ should open up the TurboGears2 welcome page. By default newly quickstarted projects provide a bunch of pages to guide the user through some of the foundations of TurboGears2 web applications. Taking a look at the http://127.0.0.1:8080/about page can provide a great overview of your newly quickstarted project.