Файл: pyramid.pdf

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

5.5. RUNNING THE PROJECT APPLICATION

> ..\Scripts\python.exe setup.py test -q

Here’s sample output from a test run on UNIX:

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

running egg_info

writing requirements to MyProject.egg-info/requires.txt writing MyProject.egg-info/PKG-INFO

writing top-level names to MyProject.egg-info/top_level.txt

writing dependency_links to MyProject.egg-info/dependency_links.txt writing entry points to MyProject.egg-info/entry_points.txt

reading manifest file ’MyProject.egg-info/SOURCES.txt’ writing manifest file ’MyProject.egg-info/SOURCES.txt’ running build_ext

..

----------------------------------------------------------------------

Ran 1 test in 0.108s

OK

latex-note.png

The -q option is passed to the setup.py test command to limit the output to a stream of dots. If you don’t pass -q, you’ll see more verbose test result output (which normally isn’t very useful).

The tests themselves are found in the tests.py module in your pcreate generated project. Within a project generated by the starter scaffold, a single sample test exists.

5.5 Running The Project Application

Once a project is installed for development, you can run the application it represents using the pserve command against the generated configuration file. In our case, this file is named development.ini.

On UNIX:

41

5. CREATING A PYRAMID PROJECT

$ ../bin/pserve development.ini

On Windows:

> ..\Scripts\pserve development.ini

Here’s sample output from a run of pserve on UNIX:

$ ../bin/pserve development.ini Starting server in PID 16601.

serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

By default, Pyramid applications generated from a scaffold will listen on TCP port 6543. You can shut down a server started this way by pressing Ctrl-C.

The default server used to run your Pyramid application when a project is created from a scaffold is named Waitress. This server is what prints the serving on... line when you run pserve. It’s a good idea to use this server during development, because it’s very simple. It can also be used for light production. Setting your application up under a different server is not advised until you’ve done some development work under the default server, particularly if you’re not yet experienced with Python web development. Python web server setup can be complex, and you should get some confidence that your application works in a default environment before trying to optimize it or make it “more like production”. It’s awfully easy to get sidetracked trying to set up a nondefault server for hours without actually starting to do any development. One of the nice things about Python web servers is that they’re largely interchangeable, so if your application works under the default server, it will almost certainly work under any other server in production if you eventually choose to use a different one. Don’t worry about it right now.

You can change the port on which the server runs on by changing the development.ini file. For example, you can change the port = 6543 line in the development.ini file’s [server:main] section to port = 8080 to run the server on port 8080 instead of port 6543.

For more detailed information about the startup process, see Startup. For more information about environment variables and configuration file settings that influence startup and runtime behavior, see Environment Variables and .ini File Settings.

42

5.6. VIEWING THE APPLICATION

5.5.1 Reloading Code

During development, it’s often useful to run pserve using its --reload option. When --reload is passed to pserve, changes to any Python module your project uses will cause the server to restart. This typically makes development easier, as changes to Python code made within a Pyramid application is not put into effect until the server restarts.

For example, on UNIX:

$ ../bin/pserve development.ini --reload Starting subprocess with file monitor Starting server in PID 16601.

serving on http://0.0.0.0:6543

Now if you make a change to any of your project’s .py files or .ini files, you’ll see the server restart automatically:

development.ini changed; reloading...

-------------------- Restarting --------------------

Starting server in PID 16602. serving on http://0.0.0.0:6543

Changes to template files (such as .pt or .mak files) won’t cause the server to restart. Changes to template files don’t require a server restart as long as the pyramid.reload_templates setting in the development.ini file is true. Changes made to template files when this setting is true will take effect immediately without a server restart.

5.6 Viewing the Application

Once your application is running via pserve, you may visit http://localhost:6543/ in your browser. You will see something in your browser like what is displayed in the following image:

43

5. CREATING A PYRAMID PROJECT

This is the page shown by default when you visit an unmodified pcreate generated starter application in a browser.

5.6.1 The Debug Toolbar

If you click on the image shown at the right hand top of the page (“^DT”), you’ll be presented with a debug toolbar that provides various niceties while you’re developing. This image will float above every HTML page served by Pyramid while you develop an application, and allows you show the toolbar as necessary. Click on Hide to hide the toolbar and show the image again.

44

5.6. VIEWING THE APPLICATION

If you don’t see the debug toolbar image on the right hand top of the page, it means you’re browsing from a system that does not have debugging access. By default, for security reasons, only a browser originating from localhost (127.0.0.1) can see the debug toolbar. To allow your browser on a remote system to access the server, add the a line within the [app:main] section of the development.ini file in the form debugtoolbar.hosts = X.X.X.X. For example, if your Pyramid application is running on a remote system, and you’re browsing from a host with the IP address 192.168.1.1, you’d add something like this to enable the toolbar when your system contacts Pyramid:

[app:main]

# .. other settings ...

debugtoolbar.hosts = 192.168.1.1

For more information about what the debug toolbar allows you to do, see the documentation for pyramid_debugtoolbar.

45