Hacking on this Code

I’m always open to contributions from others provided that the are not completely worthless. I do request that you follow a few basic rules though.

  • (Almost) All code is tested: if you think that your contributions do not require tests for whatever reason, please justify it.

  • All tests pass. This is non-negotiable. If you cannot get a particular test case to pass. Submit the PR on github and we can probably work through it. What I won’t do is accept code that breaks a pile of tests without any effort to fix them. Run env/bin/tox to run the tests.

  • Features are documented. I use sphinx for all documentation. Edit the documentation sources as required and make sure that running python setup.py build_sphinx produces something reasonable.

I apologize for being pretty opinionated about this but code quality doesn’t disappear suddenly, it continually degrades. This set of minimum requirements is my attempt to help prevent quality issues.

Getting Started

Congratulations for not being immediately put off by my attitude ;) Let’s get started. First thing is to create a new sandbox for you to play in. If you are using Python 3.4 or newer, use pyvenv env to create a new virtual environment in the env directory. Otherwise, install virtualenv and run virtualenv env to create the environment.


If you did not chuckle at the previous line, then you really do need to pay careful attention to it. Use virtual environments for developing code.

Once you have an environment, install the requirements listed in dev-requirements.txt. This is a pip-formatted requirements file that will pull in packages that the code depends on as well as packages required to test, document, and generally hack on the code base.


$ python3 -mvenv env
$ env/bin/pip install -r dev-requirements.txt

Running Tests

Tests are written using the standard unittest package and run using nose and tox.

$ env/bin/tox


All documentation is written in ReStructuredText with HTML generated by the sphinx utility.

$ env/bin/python setup.py build_sphinx

The HTML output is written to build/sphinx/html.