Skip to main content

Template system for project skeletons

Project description


.. image::

.. image::

Voodoo is a template system for project skeletons (similar to the template part
of PasteScript):

* It can make a copy of a project skeleton processing some files, filter others, etc.
* Works with **local** paths and **git/hg URLs**.
* It generates a beautiful output and take care of not overwrite existing files, unless instructed to do so.
* BSD License. See ``LICENSE`` for more details.

.. image::
:alt: Voodoo sample output as used in a program.

*Above, Voodoo sample output as used in a program*


* Pypy or Python 2.6, 2.7, 3.3 or newer.

* It also uses the Jinja2 and Colorama Python libraries.

As a command line tool

Install it by doing::

$ pip install voodoo

Then, whenever you want to clone a project template to make a new project, do::

$ voodoo <Git URL or path to another folder> <New project name>


$ voodoo myapp

Or in your programs

First of all install it and/or add it to your requirements.txt::

$ pip install voodoo

The API is very simple. A ``render_skeleton`` function that takes two
absolute paths: the project skeleton to process, and where to copy it.:

.. code:: python

from voodoo import render_skeleton

render_skeleton(skeleton_path, new_project_path)

It also provide a ``prompt`` and ``prompt_bool`` functions that take
user input, to help you to make interactive scripts.

How it works

Files inside the skeleton are be copied to destination directly, unless
are suffixed with the extension '.tmpl'. In that case, the templating
engine will be used to render them.

A slightly customized Jinja2 templating is used. The main difference is
that variables are referenced with ``[[ name ]]`` instead of
``{{ name }}`` and blocks are ``[% if name %]`` instead of
``{% if name %}``. To read more about templating see the `Jinja2
documentation <>`__.

Use the data argument to pass whatever context you want to be available
in the templates. The arguments can be any valid Python value, even a

.. code:: python

from hashlib import sha256
from os import urandom
from voodoo import render_skeleton

data = {
'package': 'demo',
'py3': True,
'make_secret': lambda: sha256(urandom(48)).hexdigest()
render_skeleton(skeleton_path, new_project_path, data=data)

so in your template you can have:

.. code:: jinja

import [[ package ]]

secret = '[[ make_secret() ]]'
[% if py3 %]
msg = 'Python 3!'
[% else %]
msg = 'meh'
[% endif %]

Using it in a script

It's easy to integrate Voodoo with your own scripts. The following
example it's a classic make new project script found in many popular

.. code:: python

from os.path import join, dirname, basename
from voodoo import render_skeleton

default_context = {
'foo': 'bar',
SKELETON_PATH = join(dirname(__file__), '..', 'tests', 'demo')

def new_project(path, options):
data = default_context.copy()
data['project_name'] = basename(path)
render_skeleton(SKELETON_PATH, path, data=data, **options)

if __name__ == '__main__':
import argparse

parser = argparse.ArgumentParser(description='Create a new project')
parser.add_argument('path', help='The name or fullpath of the new project')
parser.add_argument('-p', '--pretend', action='store_true',
help='Run but do not make any changes')
parser.add_argument('-f', '--force', action='store_true',
help='Overwrite files that already exist, without asking')
parser.add_argument('-s', '--skip', action='store_true',
help='Skip files that already exist, without asking')
parser.add_argument('-q', '--quiet', action='store_true',
help='Suppress status output')

args = parser.parse_args()
da = vars(args)
new_project(da.pop('path'), da)

You can se this example working in the examples folder. Play with it,
generate a new project and manually update some files. Then run the
script again to see how it detects what files has changed, and what
files are identical and with no need of regeneration.

An interactive version of this script could be made using the
``voodoo.prompt`` and/or the ``voodoo.prompt_bool`` helper functions.

VCS Support

Voodoo supports rendering project skeletons from a version control
system repository. Git and Mercurial are supported. It requires a
working VCS command on your path: git or hg.

The forms of the URL is the same that the ``pip`` installer uses,
detecting the type of VCS using URL prefixes: "git+" or "hg+".


Currently supports cloning over ``git``, ``git+https`` and ``git+ssh``::


Passing branch names, a commit hash or a tag name is possible like so::



The supported schemes are: ``hg+http``, ``hg+https``, ``hg+static-http``
and ``hg+ssh``::


You can also specify a revision number, a revision hash, a tag name or a
local branch name like so::




``render_skeleton (src_path, dst_path, data=None, filter_ext=None, pretend=False, force=False, skip=False, quiet=False, envops=None)``

Absolute path to the project skeleton

Absolute path to where to render the skeleton

Data to be passed to the templates, as context.

A list of names or shell-style patterns matching files or folders that musn't be copied. The default is: ``['.*', '~*', '*.py[co]']``

A list of names or shell-style patterns matching files or folders that must be included, even if its name are in the filter_this list. Eg: ``['.gitignore']``. The default is an empty list.

Run but do not make any changes

Overwrite files that already exist, without asking

Skip files that already exist, without asking

Suppress the status output

Extra options for the Jinja template environment.


``prompt (text, default=None)``

Ask a question via raw_input() and return their answer.

prompt text

default value if no answer is provided.


``prompt_bool (text, default=False, yes_choices=None, no_choices=None)``

Ask a yes/no question via raw_input() and return their answer.

prompt text

default value if no answer is provided.

default ``['y', 'yes', '1', 'on', 'true', 't']``

default ``['n', 'no', '0', 'off', 'false', 'f']``

.. :changelog:


1.3.0 (2013-10-04)

* Command line script to clone and process templates:
Eg: `voodoo projectname`

1.2.0 (2013-08-17)

* VCS support using pip.
* Support for variable substitution in folder names

1.1.0 (2013-06-30)

* Correctly compare the rendered content of the templates (previously it always reported them as different)
* Support for Python 3.3

0.3 (2011-11-13)

* Public release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Voodoo-1.3.2.tar.gz (17.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page