If you are reading this, then you might be thinking about contributing some changes. Thank you!

The first step is to fork this repository and create a branch to hold your work. This project uses Github Pull Requests to manage contributions so you are required to have a Github account and create a personal fork of this repository. Once you have an account, a fork, and a branch, it is time to start coding. The following sections explain the common development tasks.

I do have a few expectations about pull requests:

  • 100% test coverage is maintained with minimal mock usage

  • all functionality is documented using sphinx

  • code is formatted using yapf before being committed – this applies to each and every commit

Do not let this scare you off. I’ll help you out if you run into problems testing or documenting. Submit the PR and we can work through the finer details.

Setting up your environment

$ python -mvenv env
$ ./env/bin/pip install -qe '.[dev]'
$ cp ci/git-pre-commit .git/hooks/pre-commit
$ chmod u+x .git/hooks/pre-commit

Running tests

Local tests


Locally running tests without starting the integration depedencies does not cover all of the library source code as shown in the following snippets. See Integration testing below for full test coverage.

Testing with coverage reporting
$ . ./env/bin/activate
(env) $ coverage run test -q
running test
running egg_info
writing klempner.egg-info/PKG-INFO
writing dependency_links to klempner.egg-info/dependency_links.txt
writing requirements to klempner.egg-info/requires.txt
writing top-level names to klempner.egg-info/top_level.txt
reading manifest file 'klempner.egg-info/SOURCES.txt'
reading manifest template ''
writing manifest file 'klempner.egg-info/SOURCES.txt'
running build_ext
Ran 23 tests in 0.005s

OK (skipped=1)
(env) $ coverage report
Name                   Stmts   Miss Branch BrPart  Cover   Missing
klempner/       2      0      2      0   100%
klempner/         8      0      0      0   100%
klempner/        71      4     22      0    96%   127-130
klempner/        11      2      0      0    82%   10-11
klempner/           88     18     32      1    81%   25-29, 125-142, 124->125
TOTAL                    180     24     56      1    88%
Using tox to ensure version compatibility
(env) $ tox -p auto
✔ OK py37 in 1.885 seconds
✔ OK py27 in 1.934 seconds
✔ OK py35 in 2.081 seconds
✔ OK py36 in 2.11 seconds
___________________________________________________ summary ___________________________________________________
  py27: commands succeeded
  py35: commands succeeded
  py36: commands succeeded
  py37: commands succeeded
  congratulations :)

Integration testing

The integration tests require that you have some additional services running. This project runs the dependencies using docker so you will need access to a docker host. You can install docker from for the majority of operating systems. Once docker is installed, running the integrated tests is simple.

Full coverage testing in docker-compose
$ docker-compose run --rm integration-test
Creating network "klempner_default" with the default driver
Creating klempner_consul_1 ... done
Building package...
Running tests..........................
Name                   Stmts   Miss Branch BrPart  Cover   Missing
klempner/       2      0      2      0   100%
klempner/         8      0      0      0   100%
klempner/        71      0     22      0   100%
klempner/        11      0      0      0   100%
klempner/           88      0     32      0   100%
TOTAL                    180      0     56      0   100%
Ran 26 tests in 0.648s


Checking code style

(env) $ yapf -dpr klempner tests
(env) $ flake8

Building documents

(env) $ ./ build_sphinx

The output is in build/sphinx/html/index.html.