Файл: pyramid.pdf

37.9. DISTRIBUTING YOUR APPLICATION

37.9 Distributing Your Application

Once your application works properly, you can create a “tarball” from it by using the setup.py sdist command. The following commands assume your current working directory is the tutorial package we’ve created and that the parent directory of the tutorial package is a virtualenv representing a Pyramid environment.

On UNIX:

$ ../bin/python setup.py sdist

On Windows:

c:\pyramidtut> ..\Scripts\python setup.py sdist

The output of such a command will be something like:

running sdist

# ... more output ...

creating dist

tar -cf dist/tutorial-0.0.tar tutorial-0.0 gzip -f9 dist/tutorial-0.0.tar

removing ’tutorial-0.0’ (and everything under it)

Note that this command creates a tarball in the “dist” subdirectory named tutorial-0.0.tar.gz. You can send this file to your friends to show them your cool new application. They should be able to install it by pointing the easy_install command directly at it. Or you can upload it to PyPI and share it with the rest of the world, where it can be downloaded via easy_install remotely like any other package people download from PyPI.

495

37. SQLALCHEMY + URL DISPATCH WIKI TUTORIAL

496

CHAPTER

THIRTYEIGHT

CONVERTING A REPOZE.BFG APPLICATION TO PYRAMID

Prior iterations of Pyramid were released as a package named repoze.bfg. repoze.bfg users are encouraged to upgrade their deployments to Pyramid, as, after the first final release of Pyramid, further feature development on repoze.bfg will cease.

Most existing repoze.bfg applications can be converted to a Pyramid application in a completely automated fashion. However, if your application depends on packages which are not “core” parts of repoze.bfg but which nonetheless have repoze.bfg in their names (e.g. repoze.bfg.skins, repoze.bfg.traversalwrapper, repoze.bfg.jinja2), you will need to find an analogue for each. For example, by the time you read this, there will be a pyramid_jinja2 package, which can be used instead of repoze.bfg.jinja2. If an analogue does not seem to exist for a repoze.bfg add-on package that your application uses, please email the Pylons-devel maillist; we’ll convert the package to a Pyramid analogue for you.

Here’s how to convert a repoze.bfg application to a Pyramid application:

1.Ensure that your application works under repoze.bfg version 1.3 or better. See http://docs.repoze.org/bfg/1.3/narr/install.html for repoze.bfg 1.3 installation instructions. If your application has an automated test suite, run it while your application is using repoze.bfg 1.3+. Otherwise, test it manually. It is only safe to proceed to the next step once your application works under repoze.bfg 1.3+.

If your application has a proper set of dependencies, and a standard automated test suite, you might test your repoze.bfg application against repoze.bfg 1.3 like so:

497

38. CONVERTING A REPOZE.BFG APPLICATION TO PYRAMID

$ bfgenv/bin/python setup.py test

bfgenv above will be the virtualenv into which you’ve installed repoze.bfg 1.3.

2.Install Pyramid into a separate virtualenv as per the instructions in Installing Pyramid. The Pyramid virtualenv should be separate from the one you’ve used to install repoze.bfg. A quick way to do this:

$ cd ~

$ virtualenv --no-site-packages pyramidenv $ cd pyramidenv

$bin/easy_install pyramid

3.Put a copy of your repoze.bfg application into a temporary location (perhaps by checking a fresh copy of the application out of a version control repository). For example:

$ cd /tmp

$svn co http://my.server/my/bfg/application/trunk bfgapp

4.Use the bfg2pyramid script present in the bin directory of the Pyramid virtualenv to convert all repoze.bfg Python import statements into compatible Pyramid import statements. bfg2pyramid will also fix ZCML directive usages of common repoze.bfg directives. You invoke bfg2pyramid by passing it the path of the copy of your application. The path passed should contain a “setup.py” file, representing your repoze.bfg application’s setup script. bfg2pyramid will change the copy of the application in place.

$ ~/pyramidenv/bfg2pyramid /tmp/bfgapp

bfg2pyramid will convert the following repoze.bfg application aspects to Pyramid compatible analogues:

•Python import statements naming repoze.bfg APIs will be converted to Pyramid compatible import statements. Every Python file beneath the top-level path will be visited and converted recursively, except Python files which live in directories which start with a . (dot).

•Each ZCML file found (recursively) within the path will have the default xmlns attribute attached to the configure tag changed from http://namespaces.repoze.org/bfg to http://pylonshq.com/pyramid. Every ZCML file beneath the top-level path (files ending with .zcml) will be visited and converted recursively, except ZCML files which live in directories which start with a . (dot).

498

• ZCML files which contain directives that have attributes which name a repoze.bfg API module or attribute of an API module (e.g. context="repoze.bfg.exceptions.NotFound") will be converted to Pyramid compatible ZCML attributes (e.g. context="pyramid.exceptions.NotFound). Every ZCML file beneath the top-level path (files ending with .zcml) will be visited and converted recursively, except ZCML files which live in directories which start with a . (dot).

5.Edit the setup.py file of the application you’ve just converted (if you’ve been using the example paths, this will be /tmp/bfgapp/setup.py) to depend on the pyramid distribution instead the of repoze.bfg distribution in its install_requires list. If you used a scaffold to create the repoze.bfg application, you can do so by changing the requires line near the top of the setup.py file. The original may look like this:

requires = [’repoze.bfg’, ... other dependencies ...]

Edit the setup.py so it has:

requires = [’pyramid’, ... other dependencies ...]

All other install-requires and tests-requires dependencies save for the one on repoze.bfg can remain the same.

6.Convert any install_requires dependencies your application has on other add-on packages which have repoze.bfg in their names to Pyramid compatible analogues (e.g. repoze.bfg.jinja2 should be replaced with pyramid_jinja2). You may need to adjust configuration options and/or imports in your repoze.bfg application after replacing these add-ons. Read the documentation of the Pyramid add-on package for information.

7.Only if you use ZCML and add-ons which use ZCML: The default xmlns of the configure tag in ZCML has changed. The bfg2pyramid script effects the default namespace change (it changes the configure tag default xmlns from http://namespaces.repoze.org/bfg to http://pylonshq.com/pyramid).

This means that uses of add-ons which define ZCML directives in the http://namespaces.repoze.org/bfg namespace will begin to “fail” (they’re actually not really failing, but your ZCML assumes that they will always be used within a configure tag which names the http://namespaces.repoze.org/bfg

xmlns="http://namespaces.repoze.org/bfg" attribute to each tag which causes a failure, or define a namespace alias in the configure tag and prefix each failing tag. For example, change this “failing” tag instance:

499

38. CONVERTING A REPOZE.BFG APPLICATION TO PYRAMID

<configure xmlns="http://pylonshq.com/pyramid"> <failingtag attr="foo"/>

</configure>

To this, which will begin to succeed:

<configure xmlns="http://pylonshq.com/pyramid" xmlns:bfg="http://namespaces.repoze.org/bfg">

<bfg:failingtag attr="foo"/> </configure>

You will also need to add the pyramid_zcml package to your setup.py install_requires list. In Pyramid, ZCML configuration became an optional add-on supported by the pyramid_zcml package.

8. Retest your application using Pyramid. This might be as easy as:

$ cd /tmp/bfgapp

$~/pyramidenv/bin/python setup.py test

9.Fix any test failures.

10.Fix any code which generates deprecation warnings.

11.Start using the converted version of your application. Celebrate.

Two terminological changes have been made to Pyramid which make its documentation and newer APIs different than those of repoze.bfg. The concept that BFG called model is called resource in Pyramid and the concept that BFG called resource is called asset in Pyramid. Various APIs have changed as a result (although all have backwards compatible shims). Additionally, the environment variables that influenced server behavior which used to be prefixed with BFG_ (such as BFG_DEBUG_NOTFOUND) must now be prefixed with PYRAMID_.

500

CHAPTER

THIRTYNINE

RUNNING A PYRAMID APPLICATION UNDER MOD_WSGI

mod_wsgi is an Apache module developed by Graham Dumpleton. It allows WSGI programs to be served using the Apache web server.

This guide will outline broad steps that can be used to get a Pyramid application running under Apache via mod_wsgi. This particular tutorial was developed under Apple’s Mac OS X platform (Snow Leopard, on a 32-bit Mac), but the instructions should be largely the same for all systems, delta specific path information for commands and files.

latex-note.png

Unfortunately these instructions almost certainly won’t work for deploying a Pyramid application on a Windows system using mod_wsgi. If you have experience with Pyramid and mod_wsgi on Windows systems, please help us document this experience by submitting documentation to the Pylons-devel maillist.

1.The tutorial assumes you have Apache already installed on your system. If you do not, install Apache 2.X for your platform in whatever manner makes sense.

2.Once you have Apache installed, install mod_wsgi. Use the (excellent) installation instructions for your platform into your system’s Apache installation.

3.Install virtualenv into the Python which mod_wsgi will run using the easy_install program.

501

39. RUNNING A PYRAMID APPLICATION UNDER MOD_WSGI

$ sudo /usr/bin/easy_install-2.6 virtualenv

This command may need to be performed as the root user.

4. Create a virtualenv which we’ll use to install our application.

$ cd ~

$ mkdir modwsgi $ cd modwsgi

$/usr/local/bin/virtualenv --no-site-packages env

5.Install Pyramid into the newly created virtualenv:

$ cd ~/modwsgi/env

$bin/easy_install pyramid

6.Create and install your Pyramid application. For the purposes of this tutorial, we’ll just be using the pyramid_starter application as a baseline application. Substitute your existing Pyramid application as necessary if you already have one.

$ cd ~/modwsgi/env

$ bin/pcreate -s starter myapp $ cd myapp

$../bin/python setup.py install

7.Within the virtualenv directory (~/modwsgi/env), create a script named pyramid.wsgi. Give it these contents:

from pyramid.paster import get_app application = get_app(

’/Users/chrism/modwsgi/env/myapp/production.ini’, ’main’)

The first argument to get_app is the project configuration file name. It’s best to use the production.ini file provided by your scaffold, as it contains settings appropriate for production. The second is the name of the section within the .ini file that should be loaded by mod_wsgi. The assignment to the name application is important: mod_wsgi requires finding such an assignment when it opens the file.

8. Make the pyramid.wsgi script executable.

502