Introduction and Creating an Application

Following along with the examples

The examples in this guide are based on (A) Pyramid 1.3's default SQLAlchemy application and (B) the Akhet demo. (Akhet is an add-on package containing some Pylons-like support features for Pyramid.) Here are the basic steps to install and run these applications on Linux Ubuntu 11.10, but you should read Creating a Pyramid Project in the Pyramid manual before doing so:

 1# Prepare virtual Python environment.
 2
 3$ cd ~/workspace
 4$ virtualenv myvenv
 5$ source myvenv/bin/activate
 6(myvenv)$ pip install 'Pyramid>=1.3'
 7
 8# Create a Pyramid "alchemy" application and run it.
 9
10(myvenv)$ pcreate -s alchemy PyramidApp
11(myvenv)$ cd PyramidApp
12(myvenv)$ pip install -e .
13(myvenv)$ initialize_PyramidApp_db development.ini
14(myvenv)$ pserve development.ini
15Starting server in PID 3871.
16serving on http://0.0.0.0:6543
17
18# Press ctrl-C to quit server
19
20# Check out the Akhet demo and run it.
21
22(myvenv)$ git clone git://github.com/mikeorr/akhet_demo
23(myvenv)$ cd akhet_demo
24(myvenv)$ pip install -e .
25(myvenv)$ pserve development.ini
26Starting server in PID 3871.
27serving on http://0.0.0.0:6543
28
29# Check out the Pyramid source and Akhet source to study.
30
31(myvenv)$ git clone git://github.com/pylons/pyramid
32(myvenv)$ git clone git://github.com/pylons/akhet
33
34(myvenv)$ ls -F
35akhet/
36akhet_demo/
37PyramidApp/
38pyramid/
39myvenv/

Things to look for: the "DT" icon at the top-right of the page is the debug toolbar, which Pylons doesn't have. The "populate_PyramidApp" script (line 13) creates the database. If you skip this step you'll get an exception on the home page; you can "accidentally" do this to see Pyramid's interactive traceback.

The p* Commands

Pylons uses a third-party utility paster to create and run applications. Pyramid replaces these subcommands with a series of top-level commands beginning with "p":

Pylons

Pyramid

Description

Caveats

paster create

pcreate

Create an app

Option -s instead of -t

paster serve

pserve

Run app based on INI file

-

paster shell

pshell

Load app in Python shell

Fewer vars initialized

paster setup-app

populate_App

Initialize database

"App" is application name

paster routes

proutes

List routes

-

-

ptweens

List tweens

-

-

pviews

List views

-

In many cases the code is the same, just copied into Pyramid and made Python 3 compatible. Paste has not been ported to Python 3, and the Pyramid developers decided it contained too much legacy code to make porting worth it. So they just ported the parts they needed. Note, however, that PasteDeploy is ported to Python 3 and Pyramid uses it, as we'll see in the next chapter. Likewise, several other packages that were earlier spun out of Paste -- like WebOb -- have been ported to Python 3 and Pyramid still uses them. (They were ported parly by Pyramid developers.)

Scaffolds

Pylons has one paster template that asks questions about what kind of application you want to create. Pyramid does not ask questions, but instead offers several scaffolds to choose from. Pyramid 1.3 includes the following scaffolds:

Routing mechanism

Database

Pyramid scaffold

URL dispatch

SQLAlchemy

alchemy

URL dispatch

-

starter

Traversal

ZODB

zodb

The first two scaffolds are the closest to Pylons because they use URL dispatch, which is similar to Routes. The only difference between them is whether a SQLAlchemy database is configured for you. The third scaffold uses Pyramid's other routing mechanism, Traversal. We won't cover traversal in this guide, but it's useful in applications that allow users to create URLs at arbitrary depths. URL dispatch is more suited to applications with fixed-depth URL hierarchies.

To see what other kinds of Pyramid applications are possible, take a look at the Kotti and Ptah distributions. Kotti is a content management system, and serves as an example of traversal using SQLAlchemy.

Directory Layout

The default 'alchemy' application contains the following files after you create and install it:

 1PyramidApp
 2├── CHANGES.txt
 3├── MANIFEST.in
 4├── README.txt
 5├── development.ini
 6├── production.ini
 7├── setup.cfg
 8├── setup.py
 9├── pyramidapp
10│   ├── __init__.py
11│   ├── models.py
12│   ├── scripts
13│   │   ├── __init__.py
14│   │   └── populate.py
15│   ├── static
16│   │   ├── favicon.ico
17│   │   ├── pylons.css
18│   │   ├── pyramid.png
19│   ├── templates
20│   │   └── mytemplate.pt
21│   ├── tests.py
22│   └── views.py
23└── PyramidApp.egg-info
24    ├── PKG-INFO
25    ├── SOURCES.txt
26    ├── dependency_links.txt
27    ├── entry_points.txt
28    ├── not-zip-safe
29    ├── requires.txt
30    └── top_level.txt

(We have omitted some static files.) As you see, the directory structure is similar to Pylons but not identical.