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:
Ensure that your application works under
repoze.bfg
version 1.3 or better. See http://docs.repoze.org/bfg/1.3/narr/install.html forrepoze.bfg
1.3 installation instructions. If your application has an automated test suite, run it while your application is usingrepoze.bfg
1.3+. Otherwise, test it manually. It is only safe to proceed to the next step once your application works underrepoze.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 againstrepoze.bfg
1.3 like so:$ bfgenv/bin/python setup.py test
bfgenv
above will be the virtualenv into which you’ve installedrepoze.bfg
1.3.Install Pyramid into a separate virtualenv as per the instructions in 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
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
Use the
bfg2pyramid
script present in thebin
directory of the Pyramid virtualenv to convert allrepoze.bfg
Python import statements into compatible Pyramid import statements.bfg2pyramid
will also fix ZCML directive usages of commonrepoze.bfg
directives. You invokebfg2pyramid
by passing it the path of the copy of your application. The path passed should contain a “setup.py” file, representing yourrepoze.bfg
application’s setup script.bfg2pyramid
will change the copy of the application in place.$ ~/pyramidenv/bfg2pyramid /tmp/bfgapp
bfg2pyramid
will convert the followingrepoze.bfg
application aspects to Pyramid compatible analogues:- Python
import
statements namingrepoze.bfg
APIs will be converted to Pyramid compatibleimport
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 theconfigure
tag changed fromhttp://namespaces.repoze.org/bfg
tohttp://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). - 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).
- Python
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 thepyramid
distribution instead the ofrepoze.bfg
distribution in itsinstall_requires
list. If you used a scaffold to create therepoze.bfg
application, you can do so by changing therequires
line near the top of thesetup.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.Convert any
install_requires
dependencies your application has on other add-on packages which haverepoze.bfg
in their names to Pyramid compatible analogues (e.g.repoze.bfg.jinja2
should be replaced withpyramid_jinja2
). You may need to adjust configuration options and/or imports in yourrepoze.bfg
application after replacing these add-ons. Read the documentation of the Pyramid add-on package for information.Only if you use ZCML and add-ons which use ZCML: The default
xmlns
of theconfigure
tag in ZCML has changed. Thebfg2pyramid
script effects the default namespace change (it changes theconfigure
tag defaultxmlns
fromhttp://namespaces.repoze.org/bfg
tohttp://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 aconfigure
tag which names thehttp://namespaces.repoze.org/bfg
namespace as its defaultxmlns
). Symptom: when you attempt to start the application, an error such asConfigurationError: ('Unknown directive', u'http://namespaces.repoze.org/bfg', u'workflow')
is printed to the console and the application fails to start. In such a case, either add anxmlns="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:<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 yoursetup.py
install_requires
list. In Pyramid, ZCML configuration became an optional add-on supported by thepyramid_zcml
package.Retest your application using Pyramid. This might be as easy as:
$ cd /tmp/bfgapp $ ~/pyramidenv/bin/python setup.py test
Fix any test failures.
Fix any code which generates deprecation warnings.
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_
.