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:
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='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.