CHAPTER

FIVE

CREATING A PYRAMID PROJECT

As we saw in Creating Your First Pyramid Application, it’s possible to create a Pyramid application completely manually. However, it’s usually more convenient to use a scaffold to generate a basic Pyramid project.

A project is a directory that contains at least one Python package. You’ll use a scaffold to create a project, and you’ll create your application logic within a package that lives inside the project. Even if your application is extremely simple, it is useful to place code that drives the application within a package, because: 1) a package is more easily extended with new code and 2) an application that lives inside a package can also be distributed more easily than one which does not live within a package.

Pyramid comes with a variety of scaffolds that you can use to generate a project. Each scaffold makes different configuration assumptions about what type of application you’re trying to construct.

These scaffolds are rendered using the pcreate command that is installed as part of Pyramid.

5.1 Scaffolds Included with Pyramid

The convenience scaffolds included with Pyramid differ from each other on a number of axes:

•the persistence mechanism they offer (no persistence mechanism, ZODB, or SQLAlchemy).

•the mechanism they use to map URLs to code (traversal or URL dispatch).

The included scaffolds are these:

starter URL mapping via URL dispatch and no persistence mechanism.

zodb URL mapping via traversal and persistence via ZODB. Note that, as of this writing, this scaffold will not run under Python 3, only under Python 2.

alchemy URL mapping via URL dispatch and persistence via SQLAlchemy

37

5. CREATING A PYRAMID PROJECT

5.2 Creating the Project

In Installing Pyramid, you created a virtual Python environment via the virtualenv command. To start a Pyramid project, use the pcreate command installed within the virtualenv. We’ll choose the starter scaffold for this purpose. When we invoke pcreate, it will create a directory that represents our project.

In Installing Pyramid we called the virtualenv directory env; the following commands assume that our current working directory is the env directory.

On UNIX:

$ bin/pcreate -s starter MyProject

Or on Windows:

> Scripts\pcreate -s starter MyProject

The above command uses the pcreate command to create a project with the starter scaffold. To use a different scaffold, such as alchemy, you’d just change the -s argument value. For example, on UNIX:

$ bin/pcreate -s alchemy MyProject

Or on Windows:

> Scripts\pcreate -s alchemy MyProject

Here’s sample output from a run of pcreate on UNIX for a project we name MyProject:

$ bin/pcreate -s starter MyProject Creating template pyramid

Creating directory ./MyProject

# ... more output ...

Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info

38

5.3. INSTALLING YOUR NEWLY CREATED PROJECT FOR DEVELOPMENT

As a result of invoking the pcreate command, a directory named MyProject is created. That directory is a project directory. The setup.py file in that directory can be used to distribute your application, or install your application for deployment or development.

A .ini file named development.ini will be created in the project directory. You will use this .ini file to configure a server, to run your application, and to debug your application. It contains configuration that enables an interactive debugger and settings optimized for development.

Another .ini file named production.ini will also be created in the project directory. It contains configuration that disables any interactive debugger (to prevent inappropriate access and disclosure), and turns off a number of debugging settings. You can use this file to put your application into production.

The MyProject project directory contains an additional subdirectory named myproject (note the case difference) representing a Python package which holds very simple Pyramid sample code. This is where you’ll edit your application’s Python code and templates.

We created this project within an env virtualenv directory. However, note that this is not mandatory. The project directory can go more or less anywhere on your filesystem. You don’t need to put it in a special “web server” directory, and you don’t need to put it within a virtualenv directory. The author uses Linux mainly, and tends to put project directories which he creates within his ~/projects directory. On Windows, it’s a good idea to put project directories within a directory that contains no space characters, so it’s wise to avoid a path that contains i.e. My Documents. As a result, the author, when he uses Windows, just puts his projects in C:\\projects.

latex-warning.png

You’ll need to avoid using pcreate to create a project with the same as a Python standard library component. In particular, this means you should avoid using names the names site or test, both of which conflict with Python standard library packages. You should also avoid using the name pyramid, which will conflict with Pyramid itself.

5.3 Installing your Newly Created Project for Development

To install a newly created project for development, you should cd to the newly created project directory and use the Python interpreter from the virtualenv you created during Installing Pyramid to invoke the command python setup.py develop

39

5. CREATING A PYRAMID PROJECT

The file named setup.py will be in the root of the pcreate-generated project directory. The python you’re invoking should be the one that lives in the bin (or Scripts on Windows) directory of your virtual Python environment. Your terminal’s current working directory must be the newly created project directory.

On UNIX:

$ cd MyProject

$ ../bin/python setup.py develop

Or on Windows:

>cd MyProject

>..\Scripts\python.exe setup.py develop

Elided output from a run of this command on UNIX is shown below:

$ cd MyProject

$ ../bin/python setup.py develop

...

Finished processing dependencies for MyProject==0.0

This will install a distribution representing your project into the interpreter’s library set so it can be found by import statements and by other console scripts such as pserve, pshell, proutes and pviews.

5.4 Running The Tests For Your Application

To run unit tests for your application, you should invoke them using the Python interpreter from the virtualenv you created during Installing Pyramid (the python command that lives in the bin directory of your virtualenv).

On UNIX:

$ ../bin/python setup.py test -q

Or on Windows:

40