Pylons

Name	Space	Page	Section	Version	Status	Reviewed	Author(s)
Creating Templates For The paster create Command	Pylons CookBook	Creating Templates For The paster create Command	Home	1.0	Draft	False	James Gardner

Introduction

Paste is an extremely powerful package that isn't just about WSGI middleware. A few weeks ago I demonstrated how to use entry_points to create simple plugins. In this article I'm going to show you how to write just such a plugin for use Paste's project template creation facility and how to add a command to Paste's paster script.

We are going to create a template for an imaginary content management system. The template we create is going to produce a project directory structure for a Python package so we need to be able to specify a package name.

Creating The Directory Structure and Templates

The directory structure for the new project needs to look like this:

- default_project
        - +package+
            - __init__.py
            - static
                - layout
                - region
                - renderer
            - service
                - layout
                    - __init__.py
                - region
                    - __init__.py
                - renderer
                    - __init__.py
        - setup.py_tmpl
        - setup.cfg_tmpl
        - development.ini_tmpl
        - README.txt_tmpl
        - ez_setup.py

Of course, your project's directory structure might look very different. In fact the paster create command can even be used to generate directory structures which aren't project templates although this wasn't what it was designed for.

When the paster create command is run, any directories with +package+ in their name will have that portion replaced by a simplified package name and likewise any directories with +egg+ in their name will have that portion replaced by the name of the egg directory, although we don't make use of that feature in this example.

All of the files with _tmpl at the end of their filenames are treated as templates and will have the variables they contain replaced automatically. All other files will remain unchanged.

The small templating language which can be used with paster create in files ending in _tmpl is defined at http://pythonpaste.org/module-paste.util.template.html

When your users specify a package name it can include capitalisation and _ characters but bear in mind the actual name of the package will be the lowercase package name with the _ characters removed. If the package name contains an _ the egg name will contain a _ character so occasionally the +egg+ name is different to the +package+ name.

To save yourself difficulty you should always recommend to your users that they stick with package names that contain no _ character and are still unique when made lowercase.

Implementing the Code

Now that we have defined our directory structure we need to implement the commands that will convert this to a ready-to-run project. The template creation commands are implemented by a class derived from paste.script.templates.Template. Here's how ours look:

The vars arguments can all be set at run time and will be available to be used as Cheetah template variables in the files which end _tmpl. For example our the setup.py_tmpl file for the default_project might looks like this:

You can see how the variables specified in vars earlier are used to generate the actual setup.py file.

The final thing we need to do in order to use our new templates is to wire them up to the paster create command by means of an entry point. In the setup.py file of the project in which the project template we have created is going to be stored we need to add the following:

We also need to add PasteScript>=1.3 to the install_requires line.

install_requires=["PasteScript>=1.3"],

We just need to install the entry points now by running:

python setup.py develop

We should now be able to see a list of available templates with this command:

paster create --list-templates

Windows users will need to add their Python scripts directory to their path or enter the full version of the command, similar to this: C:\Python24\Scripts\paster.exe create --list-templates

You should see the following:

Available templates:
    art_project:              Art project template
    basic_package:            A basic setuptools-enabled package

There may be other projects too.

Troubleshooting

If the Art entries don't show up you should check that you can import the template.py file we created because any errors are simply ignored by the paster create command rather than printing a warning.

If you are sure your code is correct it might be that the entry points data hasn't been updated. Have a look in your Python site-packages directory and delete and the Art.egg-link files, any Art*.egg files or directories and remove any entries for art from easy_install.pth (replacing Art with whatever the name you chose for your project of course). Then re-run python setup.py develop to install the correct information again.

If you are sill having problems you might want to run this code to print out a list of all entry points. It might help you track the problem down:

Using Our Template

Now that our entry point is working we can create a new project:

paster create --template=art TestProject

You will be asked lots of questions based on the variables you setup in vars earlier. If you just push return the default will be used. What you end up with is a nice project template ready for you to start coding with!

Implementing Pylons Templates

If you regularly create lots of Pylons projects with a slightly different setup from the Pylons defaults you might want to consider creating your own Pylons template to generate the projects. You can do this in exactly the way described in this document.

First setup a new Python package, perhaps called something like CustomPylons (you obviously can't use the Pylons name because Pylons itself is already using it). Then checkout the Pylons source code and copy the pylons/templates/default_project directory into your project as a starting point. You will then have to add your custom vars and Template class and setup your entry points in the CustomPylons setup.py file.

After you have finished you should be able to create your own template, based on the Pylons one, using your CustomPylons package.