Navigation

You can extend Pyramid by creating a scaffold template. A scaffold
template is useful if you'd like to distribute a customizable configuration of
Pyramid to other users. Once you've created a scaffold, and someone has
installed the distribution that houses the scaffold, they can use the
pcreate script to create a custom version of your scaffold's template.
Pyramid itself uses scaffolds to allow people to bootstrap new projects. For
example, pcreate-salchemyMyStuff causes Pyramid to render the
alchemy scaffold template to the MyStuff directory.

A scaffold template is just a bunch of source files and directories on disk. A
small definition class points at this directory. It is in turn pointed at by a
setuptools "entry point" which registers the scaffold so it can be
found by the pcreate command.

To create a scaffold template, create a Python distribution to house
the scaffold which includes a setup.py that relies on the setuptools
package. See Packaging and Distributing Projects for more information
about how to do this. For example, we'll pretend the distribution you create
is named CoolExtension, and it has a package directory within it named
coolextension.

Once you've created the distribution, put a "scaffolds" directory within your
distribution's package directory, and create a file within that directory named
__init__.py with something like the following:

Once this is done, within the scaffolds directory, create a template
directory. Our example used a template directory named
coolextension_scaffold.

As you create files and directories within the template directory, note that:

Files which have a name which are suffixed with the value _tmpl will be
rendered, and replacing any instance of the literal string {{var}} with
the string value of the variable named var provided to the scaffold.

Files and directories with filenames that contain the string +var+ will
have that string replaced with the value of the var variable provided to
the scaffold.

Files that start with a dot (e.g., .env) are ignored and will not be
copied over to the destination directory. If you want to include a file with
a leading dot, then you must replace the dot with +dot+ (e.g.,
+dot+env).

Otherwise, files and directories which live in the template directory will be
copied directly without modification to the pcreate output location.

The variables provided by the default PyramidTemplate include project
(the project name provided by the user as an argument to pcreate),
package (a lowercasing and normalizing of the project name provided by the
user), random_string (a long random string), and package_logger (the
name of the package's logger).

Run your distribution's setup.pydevelop or setup.pyinstall command.
After that, you should be able to see your scaffolding template listed when you
run pcreate-l. It will be named coolextension because that's the name
we gave it in the entry point setup. Running pcreate-scoolextensionMyStuff will then render your scaffold to an output directory named
MyStuff.

Because different versions of Pyramid handled scaffolding differently, if you
want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
1.2.X and 1.3.X, you'll need to use something like this bit of horror while
defining your scaffold template:

Doing this hideousness will allow your scaffold to work as a pastercreate
target (under 1.0, 1.1, or 1.2) or as a pcreate target (under 1.3). If an
invoker tries to run pastercreate against a scaffold defined this way
under 1.3, an error is raised instructing them to use pcreate instead.

If you want to support Pyramid 1.3 only, it's much cleaner, and the API is
stable:

You only need to specify a paste.paster_create_template entry point target
in your setup.py if you want your scaffold to be consumable by users of
Pyramid 1.0, 1.1, or 1.2. To support only 1.3, specifying only the
pyramid.scaffold entry point is good enough. If you want to support both
pastercreate and pcreate (meaning you want to support Pyramid 1.2 and
some older version), you'll need to define both.

Existing third-party distributions which house scaffolding are available via
PyPI. The pyramid_jqm, pyramid_zcml, and pyramid_jinja2
packages house scaffolds. You can install and examine these packages to see
how they work in the quest to develop your own scaffolding.