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

mypy

Type checker

setup.cfg

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
inv mypy

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

CI/CD#

This project uses Github Actions for CI/CD: