Skip to content

DEVGUIDE.rst

Latest commit

 

History

History
189 lines (108 loc) · 3.44 KB

DEVGUIDE.rst

File metadata and controls

189 lines (108 loc) · 3.44 KB
Raw

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
ruff Code formatter and linter pyproject.toml
mypy Type checker pyproject.toml
pytest Test framework pyproject.toml
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 ruff-format
inv ruff-fix

Lint

To run all linters:

inv lint

This is the same as running each linter individually:

inv ruff-format-check
inv ruff-check
inv mypy
inv chaining-types-update-required

Test

To run all unit tests:

inv test

To build the package and documentation, then run linters and unit tests:

inv ci

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|--serve [-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: