A python package template

08 July 2014 (updated 20 November 2017)

I've been sitting on this for a while, it's time to announce it as I don't know what I can improve in it. It's a python library template with all the nuts and bolts included, designed to address packaging issues and pitfalls. Travis, Coveralls, AppVeyor, Pytest, Tox, coverage, bumpversion, isort are preconfigured. No need to futz around for 3 hours trying to figure out what's wrong with your coverage or test settings every time you create a library anymore.

It also includes a test grid configurator, along the lines of what I previously wrote about, but better, with declarative configuration.

This template errs on the side of "too much stuff" - it's easier to remove stuff you don't need than figuring out how to write it properly when you need it. Don't need sphinx docs? Easy, just delete the docs directory. Don't need basic version management, want to use something more complex? Just remove that .bumpversion.cfg.

Why is this good? *

I created this because every time I had the same problems:

  • I had to copy over configuration around from other projects, do a bit of search and replace, commit, realize it's wrong and then end up with lots of "Oooops, I forgot about this." commit messages.
  • The large amount of boilerplate required for a package is a detractor to getting a good package out there. It's daunting to write all that configuration, docs skeleton, contributor guides and whatnot - it's always more pleasing to write useful core than boring boilerplate.

The test grid configurator [1] is incredibly useful in situations where you want to test that your package works properly everywhere, in every configuration. Which you should :)

Where & how? *

Get cookiecutter:

pip install cookiecutter

And then create your library:

cookiecutter https://github.com/ionelmc/cookiecutter-pylibrary.git

Also, check the full usage instructions.

Where's the sample? *

Results-oriented people should look at the sample project - created straight from the template with no changes.

[1]Many projects have huge test matrices (e.g.: django-cms, django-rest-framework, django-extensions, django-taggit, django-filter, django-blog-zinnia, django-guardian) but I only seen one that has a test grid configurator: pytest-django.

This entry was tagged as packaging python src testing