Usage

As an example, let’s create a Python package. The Projy template mostly follows recommendations from The Hitchhiker’s Guide to Packaging.

A Python package example

Use simply:

$ projy PythonPackage TowelStuff

In the same directory as you typed this command, you now have a TowelStuff directory, with the following structure:

TowelStuff/
    bin/
    bootstrap
    CHANGES.txt
    docs/
        index.rst
    LICENSE.txt
    MANIFEST.in
    README.txt
    setup.py
    towelstuff/
        __init__.py

Each file has been created with a specific template, so the package is fully functional, yet empty. Now, let’s give a little explanation on each file. You can find further information here.

bin/, docs/ and towelstuff/ directories

Three directories are created by default:

• bin/ contains your package’s scripts ;
• docs/, contains the documentation you write for the package. A primary index.rst file waits for you to write into it. Yes, it uses reStructuredText format.
• towelstuff/, is where you put the files of your package. It is the lower case version of the project name. By default, it already contains an empty __init__.py file.

See the links for more information.

bootstrap

This file is a little treat, not present in The Hitchhiker’s Guide to Packaging. Using the BootstrapScriptFileTemplate template, it is a simple bash file creating a virtual environment easily. Use it with a simple:

$ source bootstrap

By default, it installs three packages from pypi:

• nose is “nicer testing for Python” ;
• pylint, a Python code static checker ;
• sphinx, the Python documentation generator.

Everything you need to write quality code :-) Of course, you can add any other package you may need, it’s up to you. You can even externalize this list of package to a requirement file.

CHANGES.txt

The template of the CHANGES.txt file simply contains:

v<version>, <date> -- Initial release.

LICENSE.txt

By default, the Python package template contains the GPL v3 as LICENSE.txt. Change it as your convenience.

MANIFEST.in

The manifest is an important file that contains this:

include CHANGES.txt
include LICENSE.txt
include MANIFEST.in
include README.txt
recursive-include bin *
recursive-include docs *
recursive-include towelstuff *

README.txt

The usual README file, written in reStructuredText format.

setup.py

The setup.py file created from the template contains:

# -*- coding: utf-8 -*-
""" $project setup.py script """

# system
from distutils.core import setup
from os.path import join, dirname


setup(
    name='TowelStuff',
    version='0.1.0',
    author='Stéphane Péchard',
    author_email='stephanepechard@provider.com',
    packages=['towelstuff','towelstuff.test'],
    url='http://',
    license='LICENSE.txt',
    long_description=open(join(dirname(__file__), 'README.txt')).read(),
    install_requires=[''],
    test_suite='towelstuff.test',
)

A more elaborate example: customizing the substitutions

You can modify the substitutions used by the template through the command line:

$ projy PythonPackage TowelStuff "author,Monty" "date,2012-06-18"

Then the substitutes author (normally get from git) and date (defaulted to the current day) are defined by the given values, not those computed by Projy. The format of such substitutions should be "key,value". Neither the key or the value should therefore include a comma. Leading and trailing spaces are removed from both key and value.

To know which substitutions can be overwritten this way, use the -i option as described in the dedicated section. You can add substitutions that are not listed with the -i option but they won’t have any effect if the template file does not consider them.

Options

Projy comes also with some useful command line option.

Listing templates

Type:

$ projy -l

and you’ll see the list of available templates in your installation. That’s an easy way to copy/paste the name of the template you want to use on the next command.

What’s inside a template

Type:

$ projy -i PythonPackage

and you’ll see the detailed structure of the PythonPackage template. It shows the created directories and files, with the substitutions included in the template.