Usage

As an example, let’s create some projects as the ones you usually work on.

A Python package example

First is a Python package. The Projy template mostly follows recommendations from The Hitchhiker’s Guide to Packaging. Use simply:

$ projy PythonPackage TowelStuff

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

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 component. You can find further information here.

bin/, docs/ and towelstuff/ directories

Three directories are created by this project template:
  • 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# -*- 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='you@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',
)

Look at how the content is filled with your own data (names, author, mail).

Customized 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.

A full “scooped” Django project

Starting with version 0.4, Projy includes somes post-project creation capabilities, that allows you to make almost anything you want after the files structure has been generated. Let see this with the first template using this, the Django project template. Nothing changed in the command, you type:

$ projy DjangoTemplate FunWebsite

Now, not only the Django template is used to create the project structure, but once it is done, a hook is called to do the following:

  • build the virtual environment through the use of the Makefile file;
  • create the FunWebsite Django project with the django-admin.py startproject command and the Django binary installed in the virtual environment ;
  • separate the original settings.py file into three different settings files, following recommendations from Two scoops of Django ;
  • initiate an empty git repository ;
  • do some minor adjustments to get the project as I’m used to.

This hook helps crafting a very customized Django project tree structure. It is made of Python commands and automatically run into the project directory. What it does is defined into the Django project template.

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.