skip to navigation
skip to content

Not Logged In

cliche 0.1

Tool to create Python application skeletons from templates

Cliché is the tool to create Python application skeletons from templates.

Templates are Git repositories, support custom file patterns and virtualenv installation, as well as installation of any requirements (dependencies).

Which gives Cliché users the ability to start new projects in just a few seconds.

Templates may be public Git repositories, which gives Cliché users an ability to share and reuse templates. Cliché provides few templates itself, but relies on the community to create even more end even better templates.

Why using Cliché

How many times did you start, let's say, new Flask or Django application?

And when you do so, do you copy a basic application structure from a previous similar application implemented, and then clean up the code or rename all the packages?

And how often did you forget to rename one package?

And even if some tools provide means to create basic application structures, they sometimes don't work - you probably want a more simple template, or, the contrary - a more sophisticated one and the one well adapted to your needs.

Finally, wouldn't it be nice to just use someone else application template which already exists?

And this is where Cliché stands out...

Features

  • creates an application skeleton from an arbitrary Git repository, referred hereafter as a template
  • the template may be any Git repository, local or hosted, private or public (so, yes - templates may be shared)
  • templates may contain any directory structure or any files
  • files may contain substitution placeholders, which will be replaced with values given by a user or with valid defaults
  • file names and directory names may contain substitution placeholders too (no need to rename packages any more!)
  • creates a virtualenv for you, unless asked to not to
  • installs dependencies into the virtualenv, if any are defined in the template
  • is a command-line tool; it is interactive unless asked otherwise

Installation

Use easy_install or pip to install Cliché. For example:

$ pip install cliche

Usage

Cliché installs a cliche command-line utility. Use --help to find out more on its usage. Few examples are hereafter:

$ cliche --repo https://github.com/trubeko/template-sample.git

will clone the specified template repository and expand it into current directory - ask for values to be used in the file names and file content patterns (if any are defined by the template used - like root package name or an application title), substitute them in the template; install the virtualenv and populate it with dependencies if any are declared by the template

$ cliche --repo https://github.com/trubeko/template-sample.git --directory new_app_directory

will do the same but will expand to the new_app_directory

$ cliche --force-yes --repo https://github.com/trubeko/template-sample.git

will also suppress any interactive prompts which allows it to be used in an automated environment

$ cliche --no-virtualenv --repo https://github.com/trubeko/template-sample.git

will also suppress the creation of the virtualenv, even if requirements are defined in the template; you can always create the virtualenv manually later, and populate it with the defined requirements, as they are defined in a standard pip requirements.txt file

$ cliche --help

will show the detailed usage information

Creating a template

In a nutshell, a template is any Git repository. It means that any Git repository may be cloned via Cliché. However, it doesn't necessarily make sense to clone an arbitrary repository. As Cliché adds more functionality than just cloning, there are few things you can do to the repository to use it as the template effectively.

As a reference, one may use the sample template used to test the Cliché tool itself: https://github.com/trubeko/template-sample . This template uses all of the Cliché features described hereafter.

Add basic application structure

Cliché will clone the repository with Git, so it will deliver it "as is" at first. Commit all files you want to have in a template as you would do usually with Git.

Tip: add a license file to the repository; for example, all Cliché-provided templates are licensed under LGPL (while Cliché itself is under GPL)

Tip: add README explaining the expected use of the template

Using string substitutions

Any directory name, file name or text file content may contain a substitution placeholder, which will be replaced with a value given by the end user upon the clone.

Placeholders themselves should follow the rules as defined in Template stings in the Python documentation. Basically, it is a ${placeholder_name} or $placeholder_name pattern. It is recommended to use the former in the files' content, and the latter in file names. Use $$ to mask the $ symbol anywhere in the template (or otherwise it will be accepted as a placeholder).

For example, typically, every application has its very own name of the root package - which will be used as the package directory name and may be as well referred in other source files (although, using relative imports is sometimes a better idea). In this case, directory layout may look like:

\src
    \$root_package\__init__.py
                  \main.py
\test
    \test_$root_package.py

Where test_$root_package.py may contain the following:

import unittest
from ${root_package} import main

class ${app_name}Test(unittest.TestCase):
    ...

In this example we've used two parameters: root_package and app_name. When using Cliché, parameters should be predefined in a template configuration file, for them to be identified by Cliché before expanding the template.

When expanding the template, for every declared parameter, Cliché will ask user to enter an actual value to substitute in place of it, and will as well propose a valid default (defined in the template configuration file). Cliché can as well run in a silent mode (without interactive prompts), in which case it will use defaults for all parameters.

Hint: if some parameter is used in the template, but is not defined in the template configuration file, the template will fail to expand; declaring all parameters explicitly is mandatory.

Template configuration file

The template configuration file is only used (today) to hold the parameters to substitute in the template and their defaults. It is supposed to be extended later with more configuration options, but as well be kept backward-compatible with older specifications.

The template configuration file is a template.json file in the root of the template, with a predefined structure:

{
    "parameters": {
        "param_name": "default_value",
        ...
    }
}

where param_name and default_value can be arbitrary text values, as long as param_name conforms to Python's Template stings requirements.

Defining requirements (dependencies)

When expanding the template, Cliché will install a virtualenv (unless asked otherwise) and will as well install any dependencies declared in the requirements.txt file, if the one exists in the template's root directory.

requirements.txt file is in fact consumed by pip, hence the file format. Briefly, every line in a file declares one python package to install, and, optionally, required version. For example:

Flask
mock==1.0.1
nose>=1.2.1
 
File Type Py Version Uploaded on Size
cliche-0.1.tar.gz (md5) Source 2013-12-09 5KB
  • Downloads (All Versions):
  • 50 downloads in the last day
  • 202 downloads in the last week
  • 652 downloads in the last month