Developer Guide

This guide provides an overview of the tooling this project uses and how to execute developer workflows using the developer CLI.

Python Environments

This Python project is tested against different Python versions. For local development, it is a good idea to have those versions installed so that tests can be run against each.

There are libraries that can help with this. Which tools to use is largely a matter of preference, but below are a few recommendations.

For managing multiple Python versions:

  • pyenv
  • OS package manager (e.g. apt, yum, homebrew, etc)
  • Build from source

For managing Python virtualenvs:

Tooling

The following tools are used by this project:

Tool Description Configuration
black Code formatter pyproject.toml
isort Import statement formatter setup.cfg
docformatter Docstring formatter setup.cfg
flake8 Code linter setup.cfg
pylint Code linter pylintrc
pytest Test framework setup.cfg
tox Test environment manager tox.ini
invoke CLI task execution library tasks.py

Workflows

The following workflows use developer CLI commands via invoke and are defined in tasks.py.

Autoformat Code

To run all autoformatters:

inv fmt

This is the same as running each autoformatter individually:

inv black
inv isort
inv docformatter

Lint

To run all linters:

inv lint

This is the same as running each linter individually:

inv flake8
inv pylint

Test

To run all unit tests:

inv unit

To run unit tests and builds:

inv test

Test on All Supported Python Versions

To run tests on all supported Python versions:

tox

This requires that the supported versions are available on the PATH.

Build Package

To build the package:

inv build

This will output the source and binary distributions under dist/.

Build Docs

To build documentation:

inv docs

This will output the documentation under docs/_build/.

Serve Docs

To serve docs over HTTP:

inv docs -s|--server [-b|--bind 127.0.0.1] [-p|--port 8000]

inv docs -s
inv docs -s -p 8080
inv docs -s -b 0.0.0.0 -p 8080

Delete Build Files

To remove all build and temporary files:

inv clean

This will remove Python bytecode files, egg files, build output folders, caches, and tox folders.

Release Package

To release a new version of the package to https://pypi.org:

inv release