Using the “py-generic-project” Template¶
In case you don’t have the
cookiecutter command line tool yet,
here’s how to
py-generic-project v1.2 and upwards, you need
cookiecutter v1.1, or v1.0 with degraded functionality –
pipsi installs, just issue a
pipsi upgrade cookiecutter
command and you’re done.
Creating a new Python project based on this template goes like this (make sure you’re in the directory you want your project added to):
It’s advisable to
git add the created directory directly afterwards,
before any generated files are added, that you don’t want to have in
To get your defaults for common template values
cookiecutter will ask you for when you use a template,
it makes sense to have a ~/.cookiecutterrc in your home
directory. Follow the link to see an example.
Also, you should at least check these files regarding their content and adapt them according to your needs:
project.d/classifiers.txt– Add the correct categories (a/k/a Trove classifiers) for your project.
requirements.txt– Add any Python packages you need for your project at runtime.
To bootstrap the project (as mentioned, best after
git add), use
these commands from within its directory:
. .env --yes --develop
inv ci | less -R
python -m $(./setup.py --name | tr -- - _) --help
On Windows, please install Babun to be able to use the same procedures as on a POSIX system – the installation process is easy and painless.
There are three files that define a project’s dependencies:
The first lists tools that you typically need as a developer to work on the project.
It also includes the other two, so one call to
pip install -r dev-requirements.txt
installs all of the project’s dependencies for developer use.
tox uses only the test and install requirements in the virtualenvs it creates,
because the tools aren’t needed there (or if they are, they belong to the test ones).
setup.py loads these files into the
parameters as far as possible. Special lines like
-e … and similar are skipped,
pip supports them; the idea here is to have none of those left
at the time of a release.
pytest is always added to the test requirements, since the
sub-command is mapped to use
pytest as the test runner.
There is also an optional file
setup-requirements.txt loaded into
in case you need to use some setuptools extension. If you add that file, you should
also include a matching
-r setup-requirements.txt line at the end of
This template has a few options that can be turned on and off even after initial creation, which the following terminal session demonstrates for Travis CI support.
At the moment of this writing, those feature are
cli. See the
features value in
cookiecutter.json for a
Note that since the whole template is re-created, you should make sure
that you have no pending changes in your working directory, i.e.
everything is either safely committed or stashed away. After changing
project.d/cookiecutter.json and the call to
you should look at the diff, and
git add any files that can just be
updated (e.g. typically
setup.py, and some others).
Files with considerable changes you have to merge manually, e.g. by
dumping a diff, resetting the affected files, reducing the diffs to the
changes you really want, and then applying the edited diff. Note that
the easiest way to do such a reset to the last commit is calling
git stash && git stash drop.
Another option is to work with two directories, i.e. clone a copy of
your project for the update process, perform the update, and then
selectively copy changes to your main working directory. There might be
a more stream-lined way applying some
git magic, we’ll see (ideas
are welcome). Still this is better than wading through commit logs to
catch up with an evolving template.